Arch for CVS Users

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.