[MERGE] Add two new help topics

[John Arbash Meinel]

James Westby wrote:
> Hi all,
> 
> The attached bundle adds two new help topics. The first is repositories
> that attempts to explain what they are, and things like trees/no-trees.
> 
> The second is working trees. This mainly focuses on remote working tree
> issues, and attempts to explain the options for dealing with them. Given
> that the remote working tree warning on push now points the user to it.
> This is probably the most asked question on IRC, so it obviously
> confuses people, hopefully this can help alleviate that.
> 
> Thanks,
> 
> James
> 
> 
> 
> ------------------------------------------------------------------------
> 
> # Bazaar revision bundle v0.9
> #
> # message:
> #   Add a working-trees help topic.
> #   
> #   Has both some general information and specifics about dealing with remote
> #   working trees. Because of that change the remote tree warning message to point
> #   to it. Hopefully that will give users a starting point for deciding how to
> #   cope with that situation.
> #   
> # committer: James Westby <jw+debian at jameswestby.net>
> # date: Sat 2007-04-14 03:51:44.247999907 +0100
> 
> === modified file bzrlib/builtins.py
> --- bzrlib/builtins.py
> +++ bzrlib/builtins.py
> @@ -243,6 +243,8 @@
>  
>      Since a lightweight checkout is little more than a working tree
>      this will refuse to run against one.
> +
> +    See 'bzr help working-trees' for more information on working trees.
>      """
>  
>      takes_args = ['location?']
> @@ -802,8 +804,9 @@
>                  try:
>                      tree_to = dir_to.open_workingtree()
>                  except errors.NotLocalUrl:
> -                    warning('This transport does not update the working '
> -                            'tree of: %s' % (br_to.base,))
> +                    warning('This transport does not update the working ' 
> +                            'tree of: %s. See \'bzr help ' % br_to.base + \
> +                            'working-trees\' for more information.')

^- This is a really weird way of doing this. Why not just do:

warning("This transport does not update the working "
        "tree of: %s. See 'bzr help working-trees' "
        "for more information." % (br_to.base,))

>                      push_result = br_from.push(br_to, overwrite)
>                  except errors.NoWorkingTree:
>                      push_result = br_from.push(br_to, overwrite)
> @@ -1279,11 +1282,17 @@
>      in the repository, not in the branch directory.
>  
>      example:

v- '--no-trees' is even more important now, because it is no longer the
default. (As of 0.15, IIRC).  You wouldn't really be doing "bzr checkout
--lightweight" when you have working trees.

I would leave the '--no-trees' at the beginning, remove the "or". and
just have "See 'bzr help repositories' ...".

> -        bzr init-repo --no-trees repo
> +        bzr init-repo repo
>          bzr init repo/trunk
>          bzr checkout --lightweight repo/trunk trunk-checkout
>          cd trunk-checkout
>          (add files here)
> +    or:
> +        bzr init-repo --no-trees repo
> +    as the first step to get a repository where the branches inside will not
> +    have working trees.
> +
> +    See 'bzr help repositories' for more information.

...

I think we want to be more explicit about "shared repository" versus
just "repository". Also having the term "shared repository" might help
distinguish it from darcs/git/hg which just use the term "repository" to
mean *everything*.

I tried to do a bit of prose to let you know what I was thinking. But
I'm not an English major, so you are welcome to revise as well.


> +_repositories = \
> +"""Repositories
> +

Repositories in Bazaar are where committed information is stored. It is
possible to create a shared repository which allows multiple branches to
share their information in the same location. When a new branch is
created it will first look to see if there is a containing repository it
can share.

When two branches of the same project can share a repository, there is
generally a large space savings. And for some operations (branching
within the repository) this also gives a large time savings.

Unrelated branches (eg. different projects) do not gain much from
sharing a repository, but it is frequently easier to put everything in
one location.

> +Repositories in Bazaar are a way of sharing storage between different branches.
> +If a branch is created within a shared repository then it will place the
> +revisions within it. Then when any other branches are created within the same
> +repository they will use the same revisions where they are common to both
> +branches. This has little effect for distinct projects, but where the branches
> +share some history there will be a large space saving. The space savings can
> +also become large time savings as well, for instance when branching within
> +a shared repositories.
> +

"This command takes the location ..."

> +To create a shared repository use the init-repository command (or the alias
> +init-repo). This command takes as an argument the location of the repository
> +to create. This means that 'bzr init-repository repo' will create a directory
> +named 'repo', which contains a shared repository. Any new branches that are
> +created in this directory will then be 'in' the repository, and use it for
> +storage.

^- do we need "will then be 'in' the repository"?


> +
> +It is a good idea to create a repository whenever you might create more
> +than one branch of a project. This is true for both working areas where you
> +are doing the development, and any server areas that you use for hosting
> +projects. In the latter case, if you do not want to do work directly there
> +you may wish to not have the branches have working trees. If the working trees
> +are not present then there will be less disk space used, and a lot of
> +operations will be sped up. To create a repository in which the branches will
> +not have working trees pass the '--no-trees' option to 'init-repository'.

^- "In the latter case, it is common to have branches without working
trees. Since you aren't editing the files there, there is no need to
waste disk space on a working tree. To create a repository where new
branches will not have working trees, supply the '--no-trees' option to
'init-repository'."


> +
> +Related commands:
> +
> +  init-repository   Create a shared repository. Use --no-trees to create one
> +                    in which new branches wont get a working tree.
> +"""
> +

-- Two spaces here (between top-level items)

> +_working_trees = \
> +"""Working Trees
> +
> +A working tree is the contents of a branch checked out on disk so that you can
> +see the files and edit them. The working tree is where you make changes to a
> +branch, and when you commit the current state of the working tree is the
> +snapshot that is recorded in the commit.
> +

When you push a branch to a remote system, a working tree will not be
created. If one is already present the files will not be updated. The
branch information will be updated and the working tree will be marked
as out-of-date. Updating a working tree remotely is difficult, as there
may be uncommitted changes or content conflicts that are difficult to
deal with remotely.

> +When you push a branch to a remote system then a working tree will not be
> +created, or if there is already one there it will not be updated. This is
> +because an update to the working tree can cause conflicts, and that is
> +hard to deal with remotely.
> +
> +If you have a branch with no working tree you can use the 'checkout' command
> +to create a working tree. If you run 'bzr checkout .' from the branch it will
> +create the working tree. If a subsequent push from a remote system updates the
> +branch you can update the working tree to match the branch by running 'bzr
> +update' in the branch.

^ it will create the working tree. If the branch is updated remotely,
you can update the working tree by running 'bzr update' in that directory.

> +
> +If you have a branch with a working tree that you do not want the 'remove-tree'
> +command will remove the tree if it is safe. This can be done to avoid the
> +warning about the remote working tree not being updated when pushing to the
> +branch. It can also be useful when working with a '--no-trees' repository
> +(see 'bzr help repositories').
> +
> +If you want to have a working tree on a remote machine that you push to you
> +can either run 'bzr update' in the remote branch after each push, or use some
> +other method to update the tree during the push. There is an 'rspush' plugin
> +that will update the working tree using rsync as well as doing a push. There
> +is also a 'push-and-update' plugin that automates running 'bzr update' via SSH
> +after each push.

^- I'm not sure about having plugins mentioned in bzr core... If the
functionality is that important, maybe it should be core.

> +
> +Useful commands:
> +
> +  checkout     Create a working tree when a branch does not have one.
> +  remove-tree  Removes the working tree from a branch when it is safe to do so.
> +  update       When a working tree is out of sync with it's associated branch
> +               this will update the tree to match the branch.
> +"""
> +
>  
>  topic_registry.register("revisionspec", _help_on_revisionspec,
>                          "Explain how to use --revision")
> @@ -242,4 +316,8 @@
>                          'Options that can be used with any command')
>  topic_registry.register('checkouts', _checkouts,
>                          'Information on what a checkout is')
> +topic_registry.register('repositories', _repositories,
> +                        'Basic information on shared repositories.')
> +topic_registry.register('working-trees', _working_trees,
> +                        'Information on working trees')
>  
> 
> === modified file bzrlib/tests/blackbox/test_help.py
> --- bzrlib/tests/blackbox/test_help.py
> +++ bzrlib/tests/blackbox/test_help.py
> @@ -57,6 +57,22 @@
>          self.assertContainsRe(out, 'checkout')
>          self.assertContainsRe(out, 'lightweight')
>  
> +    def test_help_repositories(self):
> +        """Smoke test for 'bzr help repositories'"""
> +        out, err = self.runbzr('help repositories')
> +        self.assertContainsRe(out, 'repository')
> +        self.assertContainsRe(out, '--no-trees')
> +        self.assertContainsRe(out, 'init-repository')
> +
> +    def test_help_working_trees(self):
> +        """Smoke test for 'bzr help working-trees'"""
> +        out, err = self.runbzr('help working-trees')
> +        self.assertContainsRe(out, 'repository')
> +        self.assertContainsRe(out, 'remote')
> +        self.assertContainsRe(out, 'checkout')
> +        self.assertContainsRe(out, 'update')
> +        self.assertContainsRe(out, 'remove-tree')
> +

I think you could do:

self.assertEqual(bzrlib.help_topics._workingtree, out)

rather than using assertContainsRe to approximate that. Just a thought.
(If we are line wrapping, etc, obviously that won't work)

>      def test_help_commands(self):
>          dash_help  = self.runbzr('--help commands')[0]
>          commands   = self.runbzr('help commands')[0]

I like where this is going, and I think it is something we want to
include in 0.16. (+0)

John
=:->