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

[Martitza Mendez]

On Wed, May 18, 2011 at 11:53 AM, Martin Pool <mbp at canonical.com> wrote:

> 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
>

Thank you Martin and Gordon for your comments.  I've been trying to think of
a concise or "simple" way to say these things, and I think you've convinced
me that it may already be as simple as the truth allows.  I think this note
from Martin

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.
>

and this note from Gordon

So you can think of it [update] has applying the diff for each revision to
> your
> working tree since you last updated.
>

are helpful ways of thinking.  I agree that the language in the help (and in
the User's Guide) could be precised, but it might also be that it makes
better sense to a native English speaker than me.

Thanks,
~M
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/bazaar/attachments/20110518/dacba57c/attachment-0001.html>