Merge lp:~mbp/bzr/help into lp:bzr

[Martin Pool]

Better help for update and revert. (Thanks Maritza.)

[Jonathan Riddell (jr)]

typo: "Update the a working tree"

[Jonathan Riddell (jr)]

"the tree's branch has changed and the tree is out of date: 'bzr commit' may tell you this."

This doesn't read quite right to me, the colon suggests to me that bzr commit is a course of action to take whereas the intention is to indicate that is will already have been run

I'd use

"the tree's branch has changed and the tree is out of date, 'bzr commit' may have warned you of this."

[Martin Pool (mbp)]

good idea.

[Jonathan Riddell (jr)]

"Revert changes files from a working tree" -> "Revert changed files from a working tree"

[Jonathan Riddell (jr)]

"you wish to temporarily revisit an old revision, or" might be nicer if this specified that it needs the -r flag
"you wish to temporarily revisit an old revision using '-r ARG', or"

Inconsistent quotes? Some places use ' some `` and one "

review: Needs Fixing

[Wouter van Heyst (larstiq)]

On Fri, May 20, 2011 at 16:01:42 -0000, Martin Pool wrote:
> Martin Pool has proposed merging lp:~mbp/bzr/help into lp:bzr.
>
> Requested reviews:
> bzr-core (bzr-core)
>
> For more details, see:
> https://code.launchpad.net/~mbp/bzr/help/+merge/61793
>
> Better help for update and revert. (Thanks Maritza.)

I like the new text! It has a couple of mentions of 'basis revision',
which might not be clear. Is there user explanation for that somewhere?
A quick grep doesn't find it, but perhaps I worry overly.

update has:

> + The new basis revision is by default the tip of the tree's branch, or
...

> + Any uncommitted changes in the working tree relative to the current basis
> + revision are carried across, by merging them into the new basis revision.

and revert:
> + Revert changes files from a working tree (or by default the whole tree) to be
> + the same as the files in the basis revision of the tree (or whatever revision
> + is specified with -r.)

Wouter van Heyst

[Vincent Ladeuil (vila)]

Can a native English speaker integrates all the useful remarks in that already well improved text ?

[Martin Pool (mbp)]

I will, I've just been away.

Unmerged revisions

5906. By Martin Pool on 2011-05-20

Better help for cmd_revert.

5905. By Martin Pool on 2011-05-20

Better help for cmd_update

=== modified file 'bzrlib/builtins.py'
--- bzrlib/builtins.py	2011-05-18 12:18:39 +0000
+++ bzrlib/builtins.py	2011-05-20 16:02:21 +0000
@@ -1429,23 +1429,28 @@
 
 
 class cmd_update(Command):
-    __doc__ = """Update a tree to have the latest code committed to its branch.
-
-    This will perform a merge into the working tree, and may generate
-    conflicts. If you have any local changes, you will still
-    need to commit them after the update for the update to be complete.
-
-    If you want to discard your local changes, you can just do a
-    'bzr revert' instead of 'bzr commit' after the update.
+    __doc__ = """Update the a working tree to be based on a new revision.
+    
+    The new basis revision is by default the tip of the tree's branch, or
+    whatever is specified by the --revision option.  If the tree's branch is
+    bound to a master branch, it will update the branch from the master, and
+    then update the working tree.
+
+    Any uncommitted changes in the working tree relative to the current basis
+    revision are carried across, by merging them into the new basis revision.
+    This merge may generate conflicts, in which case you may have to resolve
+    them before doing other work.
+
+    Use 'bzr update' when:
+     * you wish to temporarily revisit an old revision, or
+     * the tree's branch has changed and the tree is out of date: 'bzr 
+       commit' may tell you this.
 
     If you want to restore a file that has been removed locally, use
     'bzr revert' instead of 'bzr update'.
-
-    If the tree's branch is bound to a master branch, it will also update
-    the branch from the master.
     """
 
-    _see_also = ['pull', 'working-trees', 'status-flags']
+    _see_also = ['pull', 'working-trees', 'status-flags', 'conflicts', 'resolve']
     takes_args = ['dir?']
     takes_options = ['revision',
                      Option('show-base',
@@ -4300,17 +4305,33 @@
 
 
 class cmd_revert(Command):
-    __doc__ = """Revert files to a previous revision.
-
-    Giving a list of files will revert only those files.  Otherwise, all files
-    will be reverted.  If the revision is not specified with '--revision', the
-    last committed revision is used.
-
-    To remove only some changes, without reverting to a prior version, use
-    merge instead.  For example, "merge . -r -2..-3" (don't forget the ".")
-    will remove the changes introduced by the second last commit (-2), without
-    affecting the changes introduced by the last commit (-1).  To remove
-    certain changes on a hunk-by-hunk basis, see the shelve command.
+    __doc__ = """Revert working tree files to a previous revision.
+
+    Revert changes files from a working tree (or by default the whole tree) to be
+    the same as the files in the basis revision of the tree (or whatever revision
+    is specified with -r.)
+
+    Uses for 'bzr revert':
+     * You have made changes in the working tree, and want to discard your
+       changes and go back to the previously-committed tree.
+     * You have started a merge and not yet committed it, and you want to
+       discard the work done towards it.
+     * You want to undo all the changes made in a file and to take it back
+       to exactly the text it had in a previous version.
+     * Use the 'revert --forget-merges' to clear the pending-merge list,
+       without reverting the tree.
+
+    Instead of 'bzr revert':
+     * Use 'bzr update' if you want to temporarily revisit a previous
+       revision.
+     * Use 'bzr merge' with a reversed revision range if you want to undo 
+       only some changes to a file.  For example, "merge . -r -2..-3" (don't
+       forget the ".") will remove the changes introduced by the second last
+       commit (-2), without affecting the changes introduced by the last
+       commit (-1).  
+     * Use 'bzr shelve' to remove just some changes on a hunk-by-hunk basis.
+     * Use 'bzr clean-tree' to delete unversioned or ignored files from the
+       tree.
 
     By default, any files that have been manually changed will be backed up
     first.  (Files changed only by merge are not backed up.)  Backup files have
@@ -4326,14 +4347,14 @@
     created as above.  Directories containing unknown files will not be
     deleted.
 
-    The working tree contains a list of revisions that have been merged but
-    not yet committed. These revisions will be included as additional parents
-    of the next commit.  Normally, using revert clears that list as well as
-    reverting the files.  If any files are specified, revert leaves the list
-    of uncommitted merges alone and reverts only the files.  Use ``bzr revert
-    .`` in the tree root to revert all files but keep the recorded merges,
-    and ``bzr revert --forget-merges`` to clear the pending merge list without
-    reverting any files.
+    The working tree contains a list of 'pending merged' revisions that have
+    been merged but not yet committed. These revisions will be included as
+    additional parents of the next commit.  Normally, using revert clears that
+    list as well as reverting the files.  If any files are specified, revert
+    leaves the list of uncommitted merges alone and reverts only the files.
+    Use ``bzr revert .`` in the tree root to revert all files but keep the
+    recorded merges, and ``bzr revert --forget-merges`` to clear the pending
+    merge list without reverting any files.
 
     Using "bzr revert --forget-merges", it is possible to apply all of the
     changes from a branch in a single revision.  To do this, perform the merge
@@ -4346,7 +4367,7 @@
     target branches.
     """
 
-    _see_also = ['cat', 'export', 'merge', 'shelve']
+    _see_also = ['cat', 'export', 'merge', 'shelve', 'clean-tree', 'update']
     takes_options = [
         'revision',
         Option('no-backup', "Do not save backups of reverted files."),