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
these implementations are available in the respective Debian
packages. There are also
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
$ baz my-id "Alex Ng <firstname.lastname@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:
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:
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 email@example.com \ > sftp://firstname.lastname@example.org/home/arch/bar
As mentioned before, you do not need to specify the name
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
command, like so:
$ baz my-default-archive <archive name>
Reusing the above example, you would type:
$ baz my-default-archive email@example.com
You can see which is the current default archive by executing the
my-default-archive command without arguments:
$ baz my-default-archive firstname.lastname@example.org
If you need to make only one modification to a specific archive,
-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
$ 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
$ 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
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
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
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
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
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
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
baz-doc packages or search the web.
If there are any comments or suggestions, please drop me a mail here.