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.
Anonymous Checkout

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".
Generating a Patch
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.
Shared Access to a Remote Repository
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.
Creating an 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.
Importing a New Project into the 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.
Committing 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.
Advanced Use
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.

Nick Moffitt is a free software enthusiast living in
Oakland, California, where he maintains a multiuser
community shell server. He is a member of the LNX-BBC
Project and maintains GAR, nwall and the popular
game robotfindskitten.