It has been known for some time now that CVS, the workhorse revision control system for the Free Software community, is at the end of its operational lifespan. Projects such as subversion have worked hard to fix some of the more prominent flaws in CVS's design (no atomic commits, no metadata versioning), but recently a new class of source control system has arrived, championed by GNU arch.

Arch is, at its heart, a distributed system. There is no special server process, and each developer's machine can serve as an arch repository. The result is that advanced use of arch can require more work on the client side.

These advanced features often confuse CVS users who wish to upgrade to arch. Compound this with the fact that many of the documents written for arch were originally closer to API-level descriptions than actual user tutorials, and you end up with a widespread conception that arch is somehow difficult to use.

If you are a CVS user who is looking to get into arch, here's some good news: arch can be just as straightforward as CVS if you're just getting started. Many of the commands you see in the official arch documentation are not needed for basic use.

tla register-archive http://www.lnx-bbc.org/arch
tla get lnx-bbc-devel@zork.net--gar/lnx-bbc--stable

The above two commands are all you need in order to anonymously check out the stable branch of the LNX-BBC project's GAR tree. The first command causes arch to look at http://www.lnx-bbc.org/arch and determine that there is a repository there (in our case, the one called lnx-bbc-devel@zork.net--gar). You can think of it as somewhat analogous to a "cvs login", in that it creates a little bookkeeping file for the repository. No actual server login takes place, however.

The second command grabs the stable branch of the lnx-bbc project from that repository. It is almost exactly analogous to a "cvs checkout" (often shortened to "cvs co").

As the project progresses, updates will be pushed to the repository. In CVS, one would issue a "cvs up" or "cvs update" periodically to ensure that the local copy of the tree matches the current state of the checked-out branch. Well, in arch you simply issue:

tla update

and the result is the same. Arch will temporarily "tla undo" local changes before applying the repository's diffs, and will "tla redo" them afterward.

Note that in CVS, conflicts between a repository's changes and local changes are reflected inline, with dividers made of greater-than and less-than symbols. Arch prefers to use the standard patch technique of creating ".orig" and ".rej" files, so that it's much easier to track down conflicts without resorting to "grep".

In cvs, one typically executes "cvs diff -u" to generate a patch file. This patch can then be mailed to upstream authors for possible inclusion. In arch this is as simple as running:

tla what-changed --diffs

Although this is not exactly ideal. Arch stores a lot of information on which files moved where, permissions changes, and changes to binary files that cannot be stored easily in diff format. If you wish to be kind to upstream developers, you'll create a changeset, like so:

tla changes -o ,,my-illustrious-changes

This will create a directory called ",,my-illustrious-changes/" (files beginning with two commas are ignored by arch for most tasks) which you can tar up and mail off.

Since arch does not have a dedicated server process, all remote access is through network filesystems (in fact, even anonymous HTTP checkouts use WebDAV for access). This means that commit access to an arch repository is done through the SFTP subsystem of OpenSSH (or, if you insist, an ordinary FTP server).

Thus, for the archive listed above, I instead registered the archive URL as "sftp://nick@arch.lnx-bbc.org/var/www/arch", which points to a directory that has the sgid bit set and all directories are owned by the lnx-bbc developers' group. In order to make this work, we had to use a special wrapper for the SFTP server that would set group write permissions by default.

Thus, our /usr/local/lib/sftp-wrapper file reads:

#!/bin/sh
umask 002
exec /usr/lib/sftp-server $@

and our sshd.conf has the following line:

Subsystem       sftp    /usr/local/lib/sftp-wrapper

After restarting sshd, its time to make a shared archive.

To create an archive, you need to execute a command similar to "cvs init". In the case of the lnx-bbc project, I did the following:

tla make-archive lnx-bbc-devel@zork.net--gar sftp://nick@arch.lnx-bbc.org/var/www/arch

This associates an e-mail address (in our case a development mailing list, since it is a shared archive) and an archive name (gar, in our case) with the URL. It writes some administrative files to the new archive, and it is ready to go.

Note that this also works with ordinary directories. So, for example, I could have run:

mkdir ~/mynewproject
tla make-archive nick@zork.net--new ~/mynewproject

All further examples will use the nick@zork.net--new archive.

I next create a project (similar to a CVS module) in my new archive:

tla archive-setup nick@zork.net--new/testproj--newbranch--0.1

Note that the format for a project name is

<project>--<branch>--<version>.  

Now that I have created the project space, I need to add files to it. After "cd"ing into the directory with my code in it, I issue the following commands:

tla init-tree nick@zork.net--new/testproj--newbranch--0.1
tla add *.c *.h Makefile

There are no direct analog of the "cvs import" command, although some tricks can be done with combinations of "find" and "tla add". The above commands schedule all .c and .h files for inclusion in the project, as well as the Makefile. More inclusive shell glob patterns can be used if needed.

In order for these additions to take place, I need to commit my changes.

Before I can commit my changes, I need to configure arch with my identity. This is done only once, by running the "tla my-id" comand:

tla my-id "Nick Moffitt <nick@zork.net>"

Now I can easily check in changes by running:

tla commit

My editor quickly pops up with a logfile, which I fill out and save. Since remote access is via SFTP, my ssh key and local ssh agent make commits painless: I don't even need to type in a password, and I get the benefits of strong encryption.

Now that you have seen the basics of arch, I hope that you consider it at least as straightforward to use as CVS. Once you have spent some time using arch as a feature-for-feature replacement of CVS, you will want to investigate more advanced use.