Help yourself!

Newest versions of Arch include A GNU Arch Handbook, which covers the basics. It is not currently available online, so grab it from your GNU Arch sources in src/docs-tla/.

Another great resource for GNU Arch is

GNU Arch is also auto-documented:

  # Show all the available commands (long):
  tla help | less
  # Show help about a specific command:
  tla <command> -H  # e.g.: tla my-id -H

arch Meets hello-world - A Tutorial Introduction to The arch Revision Control System covers advanced use, especially the different ways to use branching (decentralised development, cherry-picking...). It begins to be outdated, but the concepts still apply. Check it at: A new version is in progress at

Here, we provide Savannah-specific information, as well as references to more complete documentation.

Setting up GNU Arch

Creating the archive

You need to do something like:

   tla make-archive s 

Alternatively, if you want to use /archives/yourproject/ as your archive, and since tla currently doesn't want to create archive in existing repositories, you can bypass this limitation by using tla make-archive locally and upload it to the server using sftp. Or fix the bug in GNU Arch.


You need a bit of manual setup before using GNU Arch:

   # Tell Arch who you are:
   tla my-id "FirstName LastName <your@email.tld>"
   # Tell Arch where your archive is:
   tla register-archive s
   # Tell Arch to use that archive by default:
   tla my-default-archive

Initial import

The initial import is a bit complicated but this should improve in future version of GNU Arch. For now the following should help:

   # Go in your current sources directory:
   cd project_directory-X.Y.Z
   # Add GNU Arch administrivia ({arch}):
   tla init-tree your_project--main--0
   # Tell GNU Arch which files to import ("register files"):
   tla inventory --names --source --both --unescaped \
    | tr '\n' '\000' \
    | xargs -0 -ifilename tla add-id "filename" 
   # Optional: check if everything is ok
   tla inventory
   # Import the registered files to your remote archive:
   tla import --setup --summary "Initial import (vX.Y.Z)"

More info:

Alternative: start an empty project

If you have no file to import, the procedure is simpler:

   # Create the project in the Arch archive:
   tla archive-setup your_project--main--0

You then can get an (empty) Arch-enabled working copy as usual - see next section.

Tools present a set of nifty tools for GNU Arch. Debian package is tla-tools.

Get a working copy of your archive

When you need to work on your project, you need to get an Arch-enabled working copy. It will include, among others, file identifiers that will remain consistent even when the file is renamed, so as to appropriately track its history:

  # Get a project in your default archive:
  tla get your_project--main--0 destination_directory

If you want to grab a working copy from another archive, you need to specify it explicitely:

  tla get -A another_project--mainline--1.0 destination_directory

(alternatively you could change your default archive with tla my-default-archive)

Working with GNU Arch

Get the work from your co-workers

When you start editing files in your working copy, synchronize it with your project archive, so as to get the latest changes:

   tla update

You can see what the latest changes are by typing:

   tla logs --summary

If you want details about a given patch (here patch-1):

   # Display the full log message (not just the summary)
   tla cat-log patch-1

   # creates a p1/ directory containing the patch-1 changeset:
   tla get-changeset patch-1 p1
   # see which files are modified and the associated diffs:
   tla show-changeset --diffs p/ | less
   # remove the downloaded changeset:
   rm -rf p1/

ToDo: how to get diffs across several patches (delta?)

Start hacking!

When you work on your code, you can see what files were modified:

   tla changes
   tla changes --diffs

When you add a new file in your project, you need to tell GNU Arch about it:

   tla add-id the_new_file

Likewise, to remove a file:

   tla rm the_file_to_delete

Renaming/moving a file:

   tla mv old_name new_name
   tla mv file1 file2 ../another/directory

(There are variants to force the file operation, eg. tell Arch to delete a file that you already deleted):

   tla delete-id already_deleted_file
   tla move-id already_renamed_file renamed_file

To check what files are unknown to GNU Arch, you can type:

   tla inventory --both

Last, this will help check if your working copy is tidy:

   tla tree-lint

Sending your changes to the archive

It is a good idea to write down some notes about what you're doing, and use these notes as a commit message. Type:

   tla make-log

which will create a commit message squeleton named like ++log.something. You can create it just before the commit, or as soon as you start hacking (so you can explain what you hacked during the coding).

When you are ready to send your changes to the archive:

   tla commit

which will use the ++log... file created above.

If it's just a small change, you may do both at once:

   tla commit -s "Summary message."

Should something wrong happen during the commit (eg: you mistyped your GPG passphrase, and get unable to acquire revision lock), break the archive lock:

   tla lock-revision --break your_project--main--0--patch-X

and then commit again.


Setting-up signatures auto-checking

Provided you installed src/tla/=gpg-check.awk as tla-gpg-check in your \$PATH, as the Debian package does, you can active it by issuing:

   mkdir -p -m 700 ~/.arch-params/signing/
   echo 'tla-gpg-check gpg_command="gpg --verify-files -"' > ~/.arch-params/signing/=default.check
   echo 'gpg --clearsign --use-agent' > ~/.arch-params/signing/=default

Then you need to import the developer's GPG key. You could cut & paste the GPG key (s)he registered at Savannah (eg. to a gpgkey.txt text file and then pass it to GPG:

   gpg --import < gpgkey.txt

ToDo: find a way to suppress the "Good signature" messages from GPG, we only need to be warned when the signature doesn't check.

Remember to install GPG agent:

Essentially it boils down to start once:

   gpg-agent --daemon > ~/.gpg_agent_info

And before to commit, type:

   source ~/.gpg_agent_info

Complementary and non-Savannah-specific information is your best bet.


In the event of a Savannah crack, signing your archive will help checking whether your codebase was altered. We recommend that you do so. This is no magic solution though - for example a developer computer could be cracked and the attacker would then be able to send validly-signed commits to the GNU Arch repository - but this will definitely makes it harder to trojan your repository.

If you'd like to get more frightened about security, Reflections on Trusting Trust by Kenneth Thompson ( is a recommended reading. (You might also need this PDF version to better read Fig. 1)

Sign an existing repository

Here we sign an unsigned repository with your own key:

   tla make-archive --listing --signed --mirror /tmp/archive/
   tla archive-mirror
   tla register-archive -d
   rm /tmp/archive/=meta-info/mirror

ToDo: now is it possible to upload the result directly at Savannah, or does this need an appointement with the Savannah Hackers?

More info:


Activate the cache

You can ask GNU Arch to extract all fetched revisions in a cache directory, so that you can avoid downloading them again later. Unchanged files are hard-linked across revisions to save space. There is only a one-time setup:

   # Register the cache ("library")
   mkdir -p ~/.arch-cache/archives/
   tla my-revision-library ~/.arch-cache/archives/
   # Tell GNU Arch to automatically update the cache,
   #  and to get all the previous patches
   tla library-config --greedy --non-sparse ~/.arch-cache/archives/

Reuse SSH connections

By reusing SSH connections, you skip the time-consuming connection establishment. SFTP is still slow though: for exemple, when issuing tla revisions, I gain 1-2 seconds out of 5-6 seconds.

GNU lsh allows to reuse connections:

   lshc -G -l you
   lshg -l you
   # ToDo: find our how to have sftp use lshg

For OpenSSH (> v4), suggests to:

   cat <<'EOF' >> ~/.ssh/config
Host arch.*
ControlMaster auto
ControlPath /tmp/%r@%h:%p

Then launch an idle background SSH process:

   ssh -f -N

When you're done, kill the background process:

   killall ssh

Converting a CVS repository to GNU Arch


You may also want to read the following consideration *About "archive conversion":

Installing the latest GNU Arch on Debian Sarge

Grab the latest source code

You can use a tarball from

Or direction from the Arch archive: check the instructions at

ToDo: The documentation emphasises on the basic features, with a centralrepository work style, but there is more than that in GNU Arch! We need to talk about distributed development. See for example

ToDo: this is getting too big. Split in several sub-pages (one per section should be good).

ToDo: merge some of this in the GNU Arch wiki, then add links

ToDo: add more traces of normal execution, for example:

 $ tla update
 * tree is already up to date

Unfortunately it is not easy to add what the user types in bold. Or, just link the appropriate GNU Arch Wiki page, such as

ToDo: find the way to automagically update ChangeLog - that's not well documented