Revision Control with Arch: Maintenance and Advanced Use

The tla replay command can be used for more powerful operations than a simple undo. One of the more compelling features of Arch is the ability to cherry-pick particular changesets from a remote archive without having to apply changes you don't need.

Consider the project, foo, maintained by Bob. Bob keeps a stable branch of the project (foo--stable) and an experimental branch (foo--experimental). All releases are generated from the stable branch—foo--stable--2.4.2 being the most recent. The experimental branch is where adventurous new features are made available in a somewhat official location.

Alice plans to work on some experimental code, so she tags off Bob's experimental branch to work in her own space:

$ tla my-id "Alice B. Hacker <abh@zork.net>"
$ tla make-archive -l abh@zork.net--work \
  sftp://abh@zork.net/home/abh/public_html/arch
$ tla archive-setup foo--hackery--0.0
$ tla register-archive http://entar.net/~bob/fooarch
$ tla tag \
  bob@entar.net--code/foo--experimental--0.0 \
  abh@zork.net--work/foo--hackery--1.0

In the process of working on her experimental features, Alice discovers a bug that Bob must have overlooked. The fix is simple, so she puts her current work aside with tla undo and checks in the fix:

$ tla undo
$ vi buggy_file.c another_buggy_file.c
$ tla commit
M  buggy_file.c
M  another_buggy_file.c
* committed
  abh@zork.net--work/foo--hackery--1.0--patch-9
$ tla redo

Alice soon finishes her changes and tells Bob where her archive lives. Bob decides that her code is acceptable for the experimental branch and star-merges it in:

$ tla get bob@entar.net--code/foo--experimental--0.0
$ cd foo--experimental--0.0/
$ tla register-archive http://zork.net/~abh/arch/
$ tla star-merge \
  abh@zork.net--work/foo--hackery--1.0

While reading Alice's changelog, Bob realizes the bug she fixed exists in the stable branch as well. Because he doesn't want to grab all of the experimental code from her hackery branch, Bob cherry-picks only the changeset that contains the bug fix:

$ tla get bob@entar.net--code/foo--stable--2.4.2
$ cd foo--stable--2.4.2/
$ tla replay \
  abh@zork.net--work/foo--hackery--1.0--patch-9

Alice and Bob were able to work together despite the fact that neither developer shared access to a single system. Neither developer had set up any sort of dedicated server; they were able to use standard stock protocols such as HTTP, SSH and SFTP. Alice's archive had the advantage of being accessible from a Web directory on the Internet, just as Bob's official archive was.

Arch provided the tools for Alice and Bob to manipulate their two separate archives, and the differences between them, using nothing more exotic than Apache and OpenSSH.

Sending so much code over the Internet always has made free software developers at least a little nervous, even if only in the back of their minds. The current system of peer review seems to have solved the problem of malicious code submissions quickly and effectively, but it would help to be able to identify each changeset's author beyond a reasonable doubt.

Arch allows developers to sign their changesets cryptographically, allowing verification of submitter identity through a web of trust. Although this does not conclusively prove the intentions of the developer in question, it raises the bar for forged submissions.

To use cryptographic signatures in Arch, you first must generate a GnuPG key.

$ gpg --gen-key

Unfortunately, signed archives are somewhat different functionally from the unsigned variety. This makes it necessary to keep a separate archive for signed commits. Running tla make-archive with the -s switch creates an archive capable of storing GnuPG signatures:

$ tla make-archive -ls jrh@zork.net--signed \
  ~/SIGNED-ARCHIVE
$ tla my-default-archive jrh@zork.net--signed

Finally, a few configuration files must be created in order for Arch to sign changesets and verify signatures. First, an awk script included in the tla distribution, called gpg-check.awk, must be installed somewhere on the system where Arch is run. The Debian tla packages install it to /usr/bin/tla-gpg-check by default. In order for Arch to verify signatures, the file ~/.arch-params/signing/=default.check should contain a single line that reads:

$ mkdir ~/.arch-params/signing/
$ echo \
 'tla-gpg-check gpg_command="gpg --verify-files -"'\
  > ~/.arch-params/signing/\=default.check

If you want keys to be downloaded automatically from a public keyserver as needed, you can add parameters such as --keyserver pgp.mit.edu --keyserver-options auto-key-retrieve to the gpg_command. This causes Arch to download keys from pgp.mit.edu as needed and verify the signatures in an archive against these keys during the get or update operations.

For Arch to sign changesets automatically that you commit to an archive created with the -s option, the ~/.arch-params/signing/=default file must be one single line like the following, substituting the address you used when you created your key:

$ echo \
  'gpg --default-key "<jrh@zork.net>" --clearsign' \
  > ~/.arch-params/signing/\=default