The Hackerlab at `regexps.com`

## Retrieving Earlier Revisions

up: arch Meets hello-world next: Shared and Public Archives prev: Checking-in Changes

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

Your First Archive which is also your default archive:

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

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

A hello-world Project in Your Archive

            % larch categories
            hello-world

            % larch branches hello-world
            hello-world--mainline

            % larch versions hello-world--mainline
            hello-world--mainline--0.1

Two Revisions of the hello-world Project

            % larch 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:

            % larch 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:

            % larch 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 it's patch level explicitly:

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

arch Meets hello-world: A Tutorial Introduction to The arch Revision Control System
The Hackerlab at `regexps.com`