The Hackerlab at `regexps.com`

## Revision Tree Libraries

up: arch next: arch Triggers

For many purposes, it is useful to have a library containing pristine trees of a large number of revisions -- for example, all of the revisions in a particular version. To be practical, though, such a library must be represented in a space-efficient way.

Unix hard-links provide a natural way to store such a library. Each successive revision in a series is a copy of the previous, but with unmodified files shared via hard-links.

`arch` provides commands to help you build, maintain, and browse such a library.

### Your Revision Library Location

To begin a new revision library, first create a new directory (`DIR` ) and then register its location:

            % larch my-revision-library DIR

You can check the location of your library with:

            % larch my-revision-library

or unregister it with:

            % larch my-revision-library -d

### Revision Library Format

A revision library has subdirectories of the form:

            ARCHIVE-NAME/CATEGORY/BRANCH/VERSION/REVISION/

Each `REVISION` directory contains the complete source of a particular revision, along with some supplemantary subdirectories and files:

            REVISION/,,patch-set/

                    The patch set that creates this revision from
                    its ancestor (unless the revision is a full-source
                    base revision).

Although the permissions on files in the revision library are determined as determined by patch sets, you must never modify files int the revision library. Doing so will cause odd errors and failures in various `arch` commands.

### Adding a Revision to the Library

You can add a selected revision to your revision library with:

            % larch library-add REVISION

That will add not only `REVISION` to the library, but all directly preceeding revisions (recursively) which are either from the same archive, or from other archives which are also in the same library. ("Directly preceeding" in this case means the previous patch level, for ordinary revisions, or the tagged revision (for revisions which are tags).)

### Finding a Revision in the Library

You can find a particular revision in the library with `library-find` :

            % larch library-find REVISION
            PATH-TO-REVSION

The output is an absolute path name to the library directory containing the revision. (Once again, you must not modify files in that directory.)

### Removing a Revision from the Library

To remove a particular revision from the library, use:

            % larch library-remove REVISION

Be aware of the following limitation in the current release: suppose that you add three successive revisions, `A` , `B` , and `C` . Then you remove `B` , then re-add `B` . Now there is a chance that the file sharing between `B` and `C` will be less than optimal, causing your library to be larger than it needs to be. (You can fix this by then removing and re-adding `C` .)

### Listing Library Contents

The command `library-archives` lists all archives with records in the library:

            % larch library-archive
            ARCHIVE-NAME
            ARCHIVE-NAME
            ...

Similarly, you can list categories, branches, versions, or revisions:

            % larch library-categories [ARCHIVE]
            % larch library-branches [ARCHIVE/CATEGORY]
            % larch library-versions [ARCHIVE/BRANCH]
            % larch library-revisions [ARCHIVE/VERSION]

### Individual Files in the Revision Library

You can locate an individual file in a revision library with:

            % archive library-file FILE [REVISION]
            PATH

or obtain its contents with:

            % archive cat-library-file FILE [REVISION]
            ...file contents...

Both commands accept the options `--tag` and `--this` . With `--tag` , the argument `FILE` is interpreted as an inventory tag, and the file with that tag is found.

With `--this` , `FILE` is interpreted as a file relative to the current directory, which should be part of a project tree. The file's inventory tag is computed and the corresponding file found in `REVISION` .

### Determining Patch Set Prerequisits

              % larch touched-files-prereqs REVISION

That command looks at the patch set for `REVISION` and at all preceding patch sets in the same version (it searches your library rather than your repository for this purpose). It reports the list of patches that touch overlapping sets of files and directories -- in other words, it tells you what patches can be applied independently of others. The command has an option to exclude from consideration file names matching a certain pattern (e.g. =README or ChangeLog ). It has an option to exclude from the output list patches which have already been applied to a given project tree. It has an option to report the specific files which are overlapped.

arch: The arch Revision Control System
The Hackerlab at `regexps.com`