Retrieving Earlier Revisions

If you've followed along with the examples in earlier chapters, you should have:

Your First Archive which is also your default archive:

        % tla my-default-archive
        lord@emf.net--2003-example

        % tla whereis-archive lord@emf.net--2003-example
        /usr/lord/examples/{archives}/2003-example

A hello-world Project in Your Archive

        % tla categories 
        hello-world

        % tla branches hello-world
        hello-world--mainline

        % tla versions hello-world--mainline
        hello-world--mainline--0.1

Two Revisions of the hello-world Project

        % tla revisions hello-world--mainline--0.1
        base-0
        patch-1

In this chapter, you'll learn how to retrieve revisions from your archive.

Checking Out the Latest Revision

You might also have a left-over project tree. If so, let's get rid of that:

        % cd ~/wd

        % ls
        hello-world

        % rm -rf hello-world

Let's suppose that you now want to get the latest sources for the hello world project. For that, you want to use the get command:

        % tla get hello-world--mainline--0.1 hello-world
        [...]


        % ls 
        hello-world

        % ls hello-world
        hw.c    main.c  {arch}

Checking Out An Earlier Revision

Let's suppose we want to check out an earlier version of the hello-world project.

Notice that in the previous example, we asked just for a particular version of the project:

        % tla get hello-world--mainline--0.1 hello-world
                    ^^^^^^^^^^^  ^^^^^^^^  ^^^ ^^^^^^^^^^^
                         |           |      |       |
                         |           |      |  target directory
                         |           |      |
                         |           |      |
                         |           |   version number
                         |           |
                         |      branch name
                         |
                   category name

We can get an earlier revision name by specifying its patch level explicitly:

        % tla get hello-world--mainline--0.1--base-0 hello-world-0
                    ^^^^^^^^^^^  ^^^^^^^^  ^^^  ^^^^^^ ^^^^^^^^^^^^^
                         |           |      |      |        |
                         |           |      |      |  target directory
                         |           |      |      |
                         |           |      | patch level name
                         |           |      |
                         |           |   version number
                         |           |
                         |      branch name
                         |
                   category name




        % ls
        hello-world     hello-world-0

        % ls hello-world-0
        hw.c    main.c  {arch}

You can see the changes made from base-0 to patch-1 with, for example, diff -r :

        % diff -r hello-world-0 hello-world
        diff -r hello-world-0/hw.c hello-world/hw.c
        7c7
        <   (void)printf ("hello warld");
        ---
        >   (void)printf ("hello world\n");
        [...]

How it Works -- Retrieving Revisions With get

Retrieving the base-0 revision is easy. As you should recall, the base-0 revision is stored as a compressed tar file of the complete source tree (see How it Works -- What import Does). When asked to retrieve base-0 , the get command essentially just unpacks that tar file.

Retrieving the patch-1 revision happens in two steps. Recall that patch-1 is stored as a changeset that describes the differences between base-0 and patch-1 (see How it Works -- commit of a New Revision). Therefore, get works by first retrieving the base-0 revision, then retrieving the patch-1 changeset, then using that changeset to modify the base-0 tree and turn it into a patch-1 tree. Internally, get uses a tla command called dopatch to apply a changeset, but if you are familiar with diff/patch patchsets, then you can think of dopatch as "patch on steroids".

Let's suppose that instead of committing just one change you'd committed many changes: not just a patch-1 revision but patch-2 , patch-3 and so forth. In essence, get will apply each changeset in order to create the revision you requested.

Note: In fact, get is a bit more complicated than is described here. On the one hand, there are performance optimizations that can spare get from having to apply a long list of changesets. On the other hand, there can be revisions created by tag rather than commit , for which different rules apply. You'll learn more about these exceptions in later chapters.