Q: Ways to explain/teach revert vs. update?

[Eli Zaretskii]

> From: Martin Pool <mbp at canonical.com>
> Date: Fri, 20 May 2011 16:59:54 +0100
> Cc: Bazaar <bazaar at lists.canonical.com>
> 
> I've attempted to improve the help for those commands in
> <https://code.launchpad.net/~mbp/bzr/help/+merge/61793>.

Thanks.

> Usage:   bzr update [DIR]
> 
> Options:
>   -v, --verbose         Display more information.
>   -h, --help            Show help message.
>   -q, --quiet           Only display errors and warnings.
>   --usage               Show usage message and options.
>   --show-base           Show base revision text in conflicts.
    ^^^^^^^^^^^
This option was not explained, and the short description is too
cryptic to be useful.

>   Use 'bzr update' when:
>    * you wish to temporarily revisit an old revision, or

Not clear why "temporarily".  Perhaps explain how this temporary
condition ends.

>   Revert changes files from a working tree (or by default the whole tree) to be
    ^^^^^^^^^^^^^^^^^^^^
You probably meant to say "Revert changes in specified FILES".

>   the same as the files in the basis revision of the tree (or whatever revision

"Basis revision" was not defined in this help text (it was in the help
text for "update").  Suggest to define before you use it.

>   When you provide files, you can use their current pathname or the pathname
    ^^^^^^^^^^^^^^^^^^^^^^
"When you specify FILES"

Using FILES in caps make it easier for the reader to understand that
you are talking about the command arguments.

>   If you have newly added files since the target revision, they will be
                                 ^
                           or directories

>   removed.

>                      Directories containing unknown files will not be
>   deleted.

Perhaps tell what will happen with such directories (conflict? failed
"revert"?).

>   The working tree contains a list of 'pending merged' revisions that have
                     ^^^^^^^^
"might contain", I think.

>   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
>   as desired.  Then doing revert with the "--forget-merges" option will keep
>   the content of the tree as it was, but it will clear the list of pending
>   merges.  The next commit will then contain all of the changes that are
>   present in the other branch, but without any other parent revisions.

I would suggest to mention "rebase" here, because that's what this
does, right?