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

[Martin Pool]

I've attempted to improve the help for those commands in
<https://code.launchpad.net/~mbp/bzr/help/+merge/61793>.

I'd appreciate very much if you can point out any problems in the new
text, or for that matter anything unclear in the other help or docs.

Martin


Purpose: Update the a working tree to be based on a new revision.
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.
  -r ARG, --revision=ARG
                        See "help revisionspec" for details.

Description:
  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'.

Aliases:  up
See also: conflicts, pull, resolve, status-flags, working-trees
Purpose: Revert working tree files to a previous revision.
Usage:   bzr revert [FILE...]

Options:
  -v, --verbose         Display more information.
  -h, --help            Show help message.
  -q, --quiet           Only display errors and warnings.
  --forget-merges       Remove pending merge marker, without changing any files.
  --usage               Show usage message and options.
  --no-backup           Do not save backups of reverted files.
  -r ARG, --revision=ARG
                        See "help revisionspec" for details.

Description:
  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
  '.~#~' 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
  name.  If you name a directory, all the contents of that directory will be
  reverted.

  If you have newly added files since the target revision, they will be
  removed.  If the files to be removed have been changed, backups will be
  created as above.  Directories containing unknown files will not be
  deleted.

  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
  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.
  Because this technique forgets where these changes originated, it may
  cause additional conflicts on later merges involving the same source and
  target branches.

See also: cat, clean-tree, export, merge, shelve, update