Merge lp:~jelmer/bzr/tweak-revert-help into lp:bzr

[Jelmer Vernooij]

Tweak the help string for 'bzr revert'.

This tweaks the help text of 'bzr revert' a bit, as discussed on the mailing list.

See https://lists.ubuntu.com/archives/bazaar/2012q1/074630.html

[Martin Pool (mbp)]

Thanks for that.

As discussed on the list, defining the command as "revert files ..." is a bit circular, so perhaps it's better to say something like "set files in the working tree" or something.

 To remove only some changes, without reverting to a prior version, use merge instead.

Perhaps that should be made more clear that revert will normally discard any uncommitted changes.

Rather than 'last committed revision' we should probably say 'working tree basis revision', which is more accurate, and we should probably mention this never changes the basis revision.

Perhaps we should contrast revert to 'update', which carries uncommitted changes, which goes to the branch tip revision by default, and which does change the basis revision.

[Jelmer Vernooij (jelmer)]

Thanks for the review and feedback. I've tweaked the description a bit more.

[Joseph Wakeling (webdrake)]

Have to say that for me at least, "last committed revision" is to me a lot more comprehensible than "working tree basis revision". What's the reason for distinguishing them? "Base revision of the current working tree" may be a more accurate description, but it may be more confusing than it's worth to users.

[Jelmer Vernooij (jelmer)]

On Mon, Mar 26, 2012 at 10:06:20AM -0000, Joseph Wakeling wrote:
> Have to say that for me at least, "last committed revision" is to me a lot more comprehensible than "working tree basis revision". What's the reason for distinguishing them? "Base revision of the current working tree" may be a more accurate description, but it may be more confusing than it's worth to users.
They *can* be different in some situations.

If I push to a remote branch with a working tree over e.g. sftp, that will only update the branch and leave the working tree alone. This is because working trees can't be accessed over sftp, only locally. In other words, the branch last revision has been changed but the working tree basis revision hasn't.

Cheers,

Jelmer

[Vincent Ladeuil (vila)]

review: Approve

[Jelmer Vernooij (jelmer)]

sent to pqm by email

=== modified file 'bzrlib/builtins.py'
--- bzrlib/builtins.py	2012-03-15 02:42:48 +0000
+++ bzrlib/builtins.py	2012-03-25 13:39:18 +0000
@@ -4728,21 +4728,28 @@
 
 
 class cmd_revert(Command):
-    __doc__ = """Revert files to a previous revision.
+    __doc__ = """\
+    Set files in the working tree back to the contents of 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.
+    working tree basis revision is used. A revert operation affects only the
+    working tree, not any revision history like the branch and repository or
+    the working tree basis revision.
 
     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.
+    To update the branch to a specific revision or the latest revision and
+    update the working tree accordingly while preserving local changes, see the
+    update command.
 
-    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
-    '.~#~' appended to their name, where # is a number.
+    Uncommitted changes to files that are reverted will be discarded.
+    Howver, 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 '.~#~' appended to their name, where # is a number.
 
     When you provide files, you can use their current pathname or the pathname
     from the target revision.  So you can use revert to "undelete" a file by