@need 3200

@node Introducing replay -- An Alternative to update
@chapter Introducing replay -- An Alternative to update

@code{update} isn't the only way to catch-up with a development path.
Another option is @code{replay}:

@example
@group
        % cd ~/wd/project-tree
        % larch replay --in-place .
        [....]
@end group
@group
@end group
@end example

What does that actually do?

@need 3200

@section An update Refresher

Let's suppose that we check out an old version of @code{hello-world}:

@example
@group
        % cd ~/wd
        % larch get hello-world--mainline--0.1--patch-1 hw-patch-1
        [...]
@end group
@group
@end group
@end example

It's easy to see that the resulting tree is not up-to-date:

@example
@group
        % cd hw-patch-1
        % larch whats-missing
        patch-2
        patch-3
@end group
@group
@end group
@end example

Now, let's suppose that we make some local changes in @code{hw-patch-1} and
then run @code{update}.   What happens?


@strong{Local changes are computed against patch-1.}  In other words, 
a changeset is created that represents the changes from a 
pristine copy of the @code{patch-1} revision to the current state
of the project tree (@code{hw-patch-1}).


@strong{A copy of patch-3 is checked out.}  @code{update} starts with a pristine
copy of the @code{patch-3} revision.


@strong{The changeset is applied to the patch-3 tree.}  The changes computed
in the first step are made to the new tree.


There's another way, though:




@need 3200

@section The replay Command

We have a local copy of the @code{patch-1}, perhaps with some local
changes:

@example
@group
        % cd ~/wd/hw-patch-1
        % larch whats-missing
        patch-2
        patch-3
@end group
@group
@end group
@end example

Recall that the @code{patch-2} and @code{patch-3} revisions each correspond to a
specific changeset, stored in the archive (see @strong{How it Works -- commit of a New Revision} in @ref{Checking-in Changes}).


We could add those changes to your local tree by using @code{get-patch} to
retrieve each changeset, and @code{dopatch} to apply it (see
@strong{get-patch Retrieves a Changeset from an Archive} in @ref{Exploring Changesets}, and
@ref{dopatch}).   That's a lot of tedious work, though, so @code{arch}
provides a more automated way to accomplish that same effect:

@example
@group
        % cd ~/wd/hw-patch-1
        % larch replay --in-place .
        [....]
        % larch whats-missing
        [no output]
@end group
@group
@end group
@end example

@code{replay --in-place} will do just what we've described: get patches
from the archive and apply them one-by-one.   One word of caution,
though: if one of those patches generates conflicts, @code{replay} will
stop there and let you fix the conflicts.  You can then pick up where
@code{replay} left off by running @code{replay --in-place} a second time.




@need 3200

@section How it Works -- replay --in-place

If you've followed along with the tutorial so far, the way that
@code{replay --in-place} works should be pretty obvious.  In fact, it's
just exactly how we described it above.  @code{replay} uses @code{whats-missing}
to find out what changes your tree is missing, @code{get-patch} to retrieve
those changesets, and @code{dopatch} to apply them.   There's a fair amount
of "bookkeeping" involved in doing that -- and that bookkeeping is
what @code{replay} automates for you.







