GNU Arch at Savannah

Note: As of 2023-06, these instructions don't work for Ineiev. Existing archives can be downloaded via rsync:

  rsync -avz your_username@arch.savannah.nongnu.org:/srv/arch/your_group .

Likewise, rsync may work for uploading the archives.

Now, GNU Arch is a decommissioned GNU package (though it's still available in distros like Trisquel), and its UI is quite complicated and different from commonly used VCSes like CVS, Subversion or Git, so it isn't likely that we'll make it fully work on Savannah unless some really interested party steps up and provides us substantial guidance.

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 http://web.archive.org/web/20080421163815/http://www.gnuarch.org/gnuarchwiki/

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.

A new version is in progress.

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 sftp://arch.sv.gnu.org/archives/your_group/myarchive1 

Alternatively, if you want to use /archives/your_group/ 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.

Setup

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 your_group@sv.gnu.org \
     sftp://your_username@arch.savannah.gnu.org/archives/your_group
   # Tell Arch to use that archive by default:
   tla my-default-archive your_group@sv.gnu.org

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 group_directory-X.Y.Z
   # Add GNU Arch administrivia ({arch}):
   tla init-tree your_group--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: http://web.archive.org/web/20080529001943/http://gnuarch.org/gnuarchwiki/Ask_Arch_questions#head-88e7aed31c2a6fbeae29a6c23cf416f6552504c4

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_group--main--0

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

Tools

http://web.archive.org/web/20081005011924/http://www.gnuarch.org/gnuarchwiki/tla-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_group--main--0 destination_directory

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

  tla get -A other_group@sv.gnu.org another_group--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_group--main--0--patch-X

and then commit again.

Signing

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. http://savannah.nongnu.org/people/viewgpg.php?user_id=20998) 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: https://savannah.gnu.org/faq/?group_id=5802&question=Download_Area_-_How_to_install_and_use_gpg-agent.txt

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

http://web.archive.org/web/20070808210801/http://www.gnuarch.org/gnuarchwiki/Signing_Archives is your best bet.

Rationale

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 (http://www.acm.org/classics/sep95/) is a recommended reading. (You might also need this PDF version http://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf 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 group@sv.gnu.org /tmp/archive/
   tla archive-mirror group@sv.gnu.org
   tla register-archive -d group@sv.gnu.org-MIRROR
   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:

• http://web.archive.org/web/20070808210801/http://www.gnuarch.org/gnuarchwiki/Signing_Archives#head-af0d7652a6fb03610c15fd099b31a2a92be98447
• http://web.archive.org/web/20070205172249/http://www.gnuarch.org/gnuarchwiki/mini_MirroringArchives

Tuning

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 arch.sv.gnu.org -l you
   lshg arch.sv.gnu.org -l you
   # ToDo: find our how to have sftp use lshg

For OpenSSH (> v4), http://www.revsys.com/writings/quicktips/ssh-faster-connections.html suggests to:

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

Then launch an idle background SSH process:

   ssh you@arch.sv.gnu.org -f -N

When you're done, kill the background process:

   killall ssh

Converting a CVS repository to GNU Arch

Check http://web.archive.org/web/20080503104335/http://www.gnuarch.org/gnuarchwiki/cscvs.

You may also want to read the following consideration *About "archive conversion": http://web.archive.org/web/20080427163916/http://www.gnuarch.org/gnuarchwiki/Arch%20and%20CVS%20in%20the%20same%20tree#head-aaa33a25bb0ce260a057294498b0dfeddf3dcb24

Installing the latest GNU Arch on Debian Sarge

http://dl.savannah.gnu.org/releases/arch4debian/sarge-backports/

Grab the latest source code

You can use a tarball from http://ftp.gnu.org/old-gnu/gnu-arch/

Or direction from the Arch archive: check the instructions at http://web.archive.org/web/20071122192029/http://gnuarch.org/arch/

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 http://web.archive.org/web/20170331060423/http://gna.org/cookbook/?func=detailitem&item_id=101

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 http://web.archive.org/web/20060709172118/http://www.gnuarch.org/gnuarchwiki/Tla_Reference/changes#head-eb01bf04c9a0e8a71c45816513df424f1c7ffedb

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