HOWTO Use GNU Arch

Debian Women - Howtos

There are currently two major implementations of GNU Arch. The first one is tla, by Tom Lord, and the second is bazaar, which is based upon tla. Both these implementations are available in the respective Debian packages. There are also tla-doc and bazaar-doc packages which contain an excellent and extensive tutorial about Arch.

That said, this HOWTO is meant to be shorter, only covering the necessary commands needed for everyday use. Since bazaar is based upon tla, this HOWTO should work for both implementations. baz, which is the executable for bazaar, will be used throughout this tutorial, but you should be able to replace that with tla without running into problems.

Before you start

Before you start, you should introduce yourself to Arch. This is done via the my-id command. It uses the following form:

$ baz my-id "Alex Ng <alex@example.org>"

This will save your name and email address permanently and will be used by Arch for example when committing changes (we'll get to that later). This is only for means of identification. Neither name nor email address need to be real, although they should, since it will make it easier to contact people working on the project.

Specifying where to get the source from

Unless you setup your own archive (which this HOWTO won't cover), obtaining the source code from a remote archive is usually the first step. Basically, this will connect to the remote site, download the source code and setup your working directory in such a way that it will keep track of the changes you make, etc.

To achieve this, you first have to register an archive. In order to do so, you will need at least a source for the archive. Optionally, you can specify a name aswell, but baz will fall back to the archive's official name if omitted.

Not specifying a name can be confusing though, because you might not actually know the original name. Especially if you work with several archives, you might get confused and have trouble finding the right archive in your archive list later.

An archive name is typically of the form:

alex@example.org--archive-name

where the part before `--' is usually the email address of the the owner of the archive. Owner is perhaps the wrong word, but it is usually the email address of the person who first created the archive. The part after `--' is the name of the archive. It should be a short name, usually the project name or something that says what the project is. It must not contain `--'.

You may have noticed several occurrences of `--'. This is a special delimiter for Arch and separates names. You have seen it in the archive name above, and it will appear a few more times during this HOWTO.

It should be noted that the email address is purely decorative and need not be the same for different people accessing the same archive. It makes sense to keep the original name though, for reasons of clarity.

The source for the archive is the location where the actual files for the archive can be found (HTTP, FTP, SFTP, local file system, ...). Let's for now assume you use SFTP, then the source could be something like this:

sftp://alex@example.org/absolute/path/to/archive

Arch uses standard URLs for the different types of locations.

The command to register an archive is register-archive. It takes the following form:

$ baz register-archive <name> <source>

where you insert the name and source as described above. An example would be:

$ baz register-archive alex@example.org--bar \
> sftp://alex@example.org/home/arch/bar

As mentioned before, you do not need to specify the name (alex@example.org--bar).

If you do authentication via password, baz will ask you for it on the command line. Note that this will not actually do anything besides adding the archive to your list of archives. That list can be displayed with:

$ baz archives

Next thing is to make the archive your default. This means the archive that you'll be working with unless specified otherwise. This is useful because it saves us the trouble of retyping the name of the archive over and over again.

The default archive is set with the my-default-archive command, like so:

$ baz my-default-archive <archive name>

Reusing the above example, you would type:

$ baz my-default-archive alex@example.org--bar

You can see which is the current default archive by executing the my-default-archive command without arguments:

$ baz my-default-archive
alex@example.org--bar

If you need to make only one modification to a specific archive, use the -A option, which takes an archive name as parameter and overrides the default archive for this one execution. Note however that this is rarely necessary, and you should probably ignore that for now.

Checking out the source code

Now that everything is set up, you are ready to get the source code. Other versioning systems call this `checking out' the source code. You do this via the get command:

$ baz get <revision>

This will need some further explanation: archives can contain more than one project. Inside an archive, contents are divided into categories, branches, versions and patch-levels, in that order. The name that refers to one specific revision is composed of at least a category and a branch. Optionally, a version and patch-level can be specified, but if absent, the most recent version and patch-level will be retrieved. Each of these parts is separated by `--' (there it is again).

A category is the most rough separation and is usually the name of the project. Branches are beyond the scope of this tutorial, but a few common ones are: trunk, main, upstream. The version is usually a major.minor version number, like 0.1, 1.0, 2.4. The patch-level is the one that changes most frequently. All this will become a bit clearer later.

For example if you wanted the source code for project foobar, from the trunk branch, version 1.0 and latest patch-level, you'd do so by the following:

$ baz get foobar--trunk--1.0

and if you need a specific patch-level, you would get the source via this command-line:

$ baz get foobar--trunk--1.0--patch-123

This will connect to the location that you specified while registering the archive and retrieve the source code. It will create a sub-directory named after the revision you specified. If you want it to create a different directory, you can specify the destination as an additional argument, like so:

$ baz get foobar--trunk--1.0--patch-123 foobar-1.0

which will download the patch-level 123 of version 1.0 of the trunk branch of project foobar into the sub-directory foobar-1.0.

Editing the source

Now that you've downloaded the source code, you can make whatever changes you wish. How you do this is heavily dependent on the language used (note that Arch is also able to version binary data like images), and is clearly out of the scope of this HOWTO.

After you've made your changes, you can list the files you've changed with:

$ baz status
$ tla changes

You can get detailed changed (in unified diff format) by running:

$ baz diff
$ tla changes --diffs
[lots of unified diff output]

If you want to display your changes to one specific file, you can use the file-diff command:

$ baz file-diff src/foo/bar.c
[list of changes in src/foo/bar.c]

Note that Arch is directory-sensitive, meaning that if you are in the sub-directory src/foo in your working directory, then running:

$ baz file-diff bar.c
[list of changes in bar.c]

will actually do the right thing.

Adding or deleting files

It might happen that you need or want to add or delete files to or from the archive. This is done by manipulating the inventory. Files are added with the add command, deleted with the delete command. Both commands take one or more arguments which will be processed in sequence. These files will be listed with A or D respectively in the list of changed files.

You can list the files currently in the inventory by running:

$ baz inventory --source

Arch can also do some magic for you and list the files that it thinks are source files:

$ baz inventory --names

The inventory command will only list files. If you want directories to be part of the listing, use the -B option.

For the curious: the inventory maps versioned files to a unique ID, which comes in handy when renaming files. The history of changes on a file is stored with the ID that the file got assigned to when it was first added. This way, the history is not lost when a file is renamed. These file IDs are stored in the .arch-ids sub-directory and should by no means modified manually, unless you absolutely positively know what you're doing.

Summarizing your changes

In order to make it easy for everybody to quickly see what you've changed, you should always write a change-log. This is done by running:

$ baz make-log

This will generate a log file, named something like ++log.foobar-1.0.... Edit this file with your favorite editor. The first line already contains Summary: after which you should summarize on one line (generally not more than 60-70 characters) what you have changed.

You can add keywords to the Keywords: line. It is not only easy to find suitable keywords, but you can always take the most important words from the summary and list them here. In case you fix a bug, you should mention the bug-number in the summary as well as the keywords line.

After the keywords line, you should leave one line blank, and after that, you can describe your changes in detail. This is not always needed. If for example you fix a typo, then you can have `Fixed typo.' as summary, and an empty detailed description.

Alternatively, you can skip this step, and proceed immediately. In that case, baz will create the log file for you and pop up your favorite editor automatically. Sometimes it happens that a commit fails for some reason, in which case your log file will not be removed. If that happens, a second baz commit command will not actually pop up your editor again, but instead use the changelog that you created earlier to commit the changes. So in case you do significant changes after a failed commit, make sure to add those to the changelog manually.

Publishing your changes

When you're done describing your changes, you save the file and quit the editor. It is now time to commit your changes back to the archive. This only works if you actually have write access to the archive. You do so by executing:

$ baz commit

which will connect to the archive and send your changes, along with a listing of the files you changed, as well as the log file you edited earlier.

If successful, it will show you a message that your changes were committed and tell you the new patch-level. The patch-level is incremented by one each time you commit changes.

Congratulations, you've just made your first contribution to project foobar! Way to go!

Updating the source

So you've done your first contributions and take a break. After a few days, you decide you want to spend more time helping out with the project. Most likely you are not the only contributor to the project, which is why you will need to synchronize your local working copy with the archive. This can be done with the update command. Simply run:

$ baz update

Where to go from here

So far, we've only covered the very basics of GNU Arch. There is a plethora of other useful and funky command that can be used, aswell as a number of additional options for the command we have seen. baz comes with built-in help which can be consulted with the following command:

$ baz help

which will give you a list of all available commands along with a short description of each. Furthermore, if you need more help with a specific command, you can run:

$ baz <command> -H

For additional tutorials, take a look at the tla-doc or baz-doc packages or search the web.

If there are any comments or suggestions, please drop me a mail here.