Introducing replay -- An Alternative to update

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

        % cd ~/wd/project-tree
        % tla replay
        [....]

What does that actually do?

An update Refresher

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

        % cd ~/wd
        % tla get hello-world--mainline--0.1--patch-1 hw-patch-1
        [...]

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

        % cd hw-patch-1
        % tla missing
        patch-2
        patch-3

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

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

A copy of patch-3 is checked out. update starts with a pristine copy of the patch-3 revision.

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:

The replay Command

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

        % cd ~/wd/hw-patch-1
        % tla missing
        patch-2
        patch-3

Recall that the patch-2 and patch-3 revisions each correspond to a specific changeset, stored in the archive (see How it Works -- commit of a New Revision).

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

        % cd ~/wd/hw-patch-1
        % tla replay
        [....]
        % tla missing
        [no output]

replay 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, replay will stop there and let you fix the conflicts. You can then pick up where replay left off by running replay a second time.

How it Works -- replay

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