Re: [Gnu-arch-users] replay vs. update

[Tom Lord]

    > From: Dustin Sallings <address@hidden>

    >   I see a lot of examples suggesting that replay and update can be used 
    > interchangeably for many applications.

    >   Is there a brief ``rule of thumb'' that one can use to decide which 
    > one to use when either seems appropriate?

I'll give you one but not without trying to give you a better
understanding of the difference.

Let's suppose that you have a version to which many changes have been
committed:

        ...
        patch-A
        patch-B
        patch-C
        ...
        patch-Z


and you have a working directory at the patch-A level:

        % tla get FOO--patch-A  wd
        % cd wd
        [...do some work...]


Now you have a `wd' that contains a patch-A tree, perhaps with some
local changes as well.

What will (a simple use of) replay do?

In essence, it will:

        % cd wd
        % rm -rf ,,tmp
        % tla get-patch patch-B ,,tmp   # retrieve the patch-B changeset
        % tla dopatch ,,tmp .           # apply it to the tree

        % rm -rf ,,tmp
        % tla get-patch patch-C ,,tmp   # repeat for each of patch-B..Z
        % tla dopatch ,,tmp . 

        ...

An exception is what happens if conflicts occur.  For example, if
patch-W conflicts with some of your local changes, `replay' will stop
to allow you to fix those, and then you can resume the operation from
there.

One key thing here is that if your local changes and one of the
patches conflict, it is the changes in the _patch_ that wind up in
.rej files.   Your local changes are given precedence.

So what will `update' do?   Conceptually, it will:

        % cd wd

        % tla undo

        # Now the wd is exactly equal to a patch-A tree.
        # Your local changes have been set aside.
        # 

        % tla replay

        # This has the effect of replay as described above,
        # only since wd starts off as exactly a patch-A tree,
        # we know that no conflicts will occur.
        # 
        # Now you have exactly a patch-Z tree.
        # 

        % tla redo

        # Reapply your local changes
        # 

If there are conflicts, these time it is the patch-Z tree that is
given precedence and your local changes that will turn up in .rej
files.

So that's a rule of thumb:  do local changes get precedence?  Yes: use
replay.  No: use update.

Why does conflict precedence matter?   One not too uncommon case is
when you know that you are going to want to discard conflicting
changes either from the archived changeset or from your local
changes.   Having the ones that you want to discard wind up in .rej
files makes it easy to quickly review and delete them.

Some subtleties:

`update' doesn't always, literally, use `replay' for its middle step.   
With suitable pristine trees or revision libraries, it can short-cut
that step and use a faster technique.

What counts as "local changes"?   If you're dealing with a tree that
has history from multiple branches, "local changes" doesn't mean
"changes I've made in wd but not committed yet" -- it means "changes
in the tree that aren't committed to the branch I'm undoing against."

To illustrate:

In the above, we had the version FOO:

   FOO
        ...
        patch-A
        patch-B
        patch-C
        ...
        patch-Z


Let's suppose we also have a version FOO--branch

   FOO:                 FOO--branch:
        ...
        patch-A ------------> patch-a
        patch-B               patch-b
        patch-C               ....
        ...                   patch-z
        patch-Z 


where that means that FOO was last merged into FOO--branch at FOO's
patch-A.   So now if I make a different wd:


        % tla get FOO--branch--patch-z  wd

what happens if I:

        % cd wd
        % tla undo FOO--patch-A

?  The result of the `undo' is a tree that is exactly `FOO--patch-A'.
The changes that `undo' sets aside, in this case, are all of the
changes in `FOO--branch--patch-a ... patch-z'.  Hopefully you can
figure out from that what would happen if, instead of `undo', you:

        % tla update FOO

Which is a trick to set aside in your Big Box of Merge Techniques from
which, on occaision, it's nice to be able to pull out Exactly the
Right Tool to solve some merging problem that has come up.

-t