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

[Martin Pool]

On 18 May 2011 19:42, Martitza Mendez <martitzam at gmail.com> wrote:
>
> I sometimes have difficulty explaining to people the behavior of 'update'
> after a 'revert'.
> I'm looking for advice which I don't think I'm finding in help or the user
> guide.
>

working trees have:
  a bunch of actual files on disk
  a note of their basis revision id, which is the one they last
committed, updated, pulled, etc
  an inventory, saying which files are versioned and what their ids are
  (a bunch of other metadata not very relevant to this including a
list of pending merged revisions, conflicts, configuration etc)

bzr revert resets the working files to the given revision, which
defaults to being the basis revision of the tree.  It never changes
the basis revision, and it throws away your local changes.

bzr update merges your uncommitted changes (relative to the current
basis) with the target revision, and writes the result into the
working files.  It then sets the basis to the target revision.

So some would say the most significant difference is that update
preserves your uncommitted changes and revert does not.

bzr commit will baulk if the wt basis is not the same as the tip of
the branch, and tell you to run update, which will fix that.

> Consider a standalone branch with a working tree.
> The branch is at revision 4 and the tree is up to date at revision 4.
> Now we revert the working tree to revision 2.
> Now if we 'update' we are told that the tree is up to date at revision 4.
> **This is the bit that some people have trouble understanding.**
> What they really need to do is revert to the head of the branch.  But they
> wonder why update did not -- as the docs say -- "Update a tree to have the
> latest code committed to its branch"
>
> So what's a good story to teach to people to think correctly about this?

After the revert, you have a bunch of uncommitted changes, which just
happen to make your tree the same as it was in r2.  When you run
update, it tries to carry those changes from r4 (your wt basis) to r4
(the tip) -- in other words it does nothing.

If you 'revert -r2' and then want to get back to the wt basis just
'revert' with no arguments again.

In general you should use revert when you want to edit a file to be
the same as it used to be; and use update when you want to revisit a
previous revision.

hth, I will see about improving the help there.  The update one is a
bit imprecise.
Martin