An Introduction to the arch Version Control System

This version control system provides for atomic commits, tracks file renames and handles project branches.

arch is a software version control system similar to CVS and Subversion that was started by programmer Tom Lord to meet his version control needs. This article introduces some of arch's key features and presents a brief tutorial on using version 1.0pre11.

One reason for arch's creation was to overcome some weaknesses in existing version control systems, such as the lack of atomic commits, the inability to keep track of file renames and difficulties when working on different branches of a project.

arch also provides support for easily and intelligently merging code from several different branches (e.g., stable, development, feature-test) of a project. Projects and revisions stored in arch have globally unique names, which allows branch and merge operations to span network boundaries.

arch was started in November 2001 and since then it has gone from a concept to having early adopters and distributed repositories. arch uses many small specialized tools to get the job done and is written using a combination of C code, awk and shell scripts.

Installing arch

First, download arch from and untar the source file.

arch's configure script frowns upon building arch in the same directory as the source code, so first you must create a build directory under arch's src directory. From the build directory, run ../configure, make and make install to get a working copy of arch.

If you don't specify an installation prefix for the configure script, arch's executables will be put in a directory called /install under the build directory. To control where install puts files use the --prefix= option when you run the configure script. If arch's bin directory isn't in your path, you can either add arch's bin directory to your PATH variable or copy the files from the =install/bin directory to your normal bin (e.g., /usr/local/bin). If you move the other arch directories (include, lib, libexec) arch won't work.

For shared archives, arch can be configured to send e-mails when project changes occur. If sendmail isn't in your path, you have to use the --with-sendmail=sendmail location option with the configure script to tell arch where it is.

While arch is the project name, larch is the program that runs all of arch's commands. You can get a list of arch commands by typing larch --help-commands and command-specific help by typing larch command --help.

Setting up arch

The first thing to do is set up your user ID so arch can correctly identify your changes. An arch ID consists of two parts: a free form part (i.e., your name) and a unique part (i.e., your e-mail address). To create your user ID use the following command:

larch my-id "John Doe <>"

Next, you will want to create an archive for arch to use. arch archives can be located on your machine or accessed over a network using FTP. To create an archive on your local machine use the following command:

larch make-archive name location

An archive's name should be globally unique so the arch manual suggests that you use your e-mail address as the base name of the archive followed by a pair of dashes and then the archive name. An example of this type of archive name would be If you are creating a shared archive, make sure that other users have write permissions to it.

Location specifies the directory to create for the archive.

To access shared archives or archives over a network you need to tell arch where they are with larch register-archive name location.

Here the archive's name should be provided by its maintainer. The archive's location can be something local, such as /usr/local/arch/{archive}, or an FTP site such as

How arch Identifies Projects in the Archive

The arch archive is organized along development paths that are made up of successive revisions of your source code files. A development path is identified by a combination of user-specified and arch-generated names. The user-specified names describe a project's category, branch and version, while the arch-generated names identify each revision of code put into the archive.

One choice for the archive category would be your application's name. The following command will create a new category in the archive called myprogram:

larch make-category myprogram

A branch name can be used to differentiate between sets of code such as development code and released code. For example, you could make a development branch with larch make-branch myprogram--development.

If you don't want to use a branch name for your code, issue the make-branch command with just the category name with nothing following it.

Finally, each project in the archive has a version number made up of digits in the format of major.minor. The archive version number is not a revision number; it does not change each time you check in changed code. A version number can be equivalent to your application's version numbers (e.g., myprogram 1.0, myprogram 1.5, myprogram 2.0, etc.). Set the version number with larch make-version myprogram--development--1.0



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

New arch info

Anonymous's picture

This article describes the older 'larch' version. The new arch is known as 'tla', and is much improved.

The official homepage for arch is and online documentation is available at

An active arch community is on #arch on freenode, and the folk there are very friendly and helpful.

Arch might take a bit of effort to change mindsets from CVS, but it is a big improvement and well worth the effort.

Re: New arch info

Anonymous's picture

The wiki is now at

Re: An Introduction to the arch Version Control System

Anonymous's picture no longer works. Is there a more current link? Or did they just vanish?

Re: An Introduction to the arch Version Control System

Anonymous's picture

The correct adress is

The move would probably have something to do with the project leader's economic problems. Remember to support him if you like it :-)

arch and ftp

Kristian's picture


sorry for stealing your time, but im trying to set up a large project using

arch instead of cvs, i htink i understood the system so far, but i cant get

arch working with my ftp server.

for tests i do something like that

larch make-archive DIR

larch my-defaul-archive

larch register-archive ftp://user:pass@localhost/DIR

now im changing into a project directory

larch make-log --new-version BS--MAIN--1.0

editing the log file....

larch add

larch commit

it fails with that error message

wftp-mkdir: 550 Create directory operation failed.

site: ftp://user:pass@localhost/

path: ,,

make-category: unable to create category

the ftp server allows creating directories, if i connect with

ftp to localhost as the specified user, i can create folders, files etc....

it seems to have something to do with the wftp session, but i dont have a clue


it would be nice if you could drop me a line,


Re: An Introduction to the arch Version Control System

Anonymous's picture

In the example "my-id" line, you need to replace the < and > with &lt; and &gt;, respectively.-- Sean Neakums

Re: An Introduction to the arch Version Control System

Anonymous's picture

Since when? I haven't had to do that for any of my archives.