This mini-guide presents a gentle overview of some of Arch's basic features. It is targeted at developers who want to use an existing project that is stored in arch. The Arch tutorial seems to be targeted at developers who want to start their own tree - it may be helpful to read this first, and then move on to other mini-guides, and then the tutorial to learn more.
This introduction was last updated to use tla 1.2_pre0.
Contents
Contents
General tla instructions
Use
$ tla help
to get a list of all the commands tla accepts with a short description of each. Use
$ tla <command> -H
to get a verbose help message for <command>.
Development on a project's archive
Getting the archive
To download the project's source code, you need three pieces of information: the archive's name (ex. tom@example.org--2004), the URI of that archive (ex. http://www.example.org/~tom/archives/2004), and the version name (ex. hello--main--1.0). First, you need to use register-archive to register the archive:
$ tla register-archive http://www.example.org/~tom/archives/2004 Registering archive: tom@example.org--2004
You can verify that the archive was actually registered using archives.
$ tla archives
tom@example.org--2004
http://www.example.org/~tom/archives/2004
Now you can use get to get a copy of the current revision.
$ tla get tom@example.org--2004/hello--main--1.0 hello * from revision library: tom@example.org--2004/hello--main--1.0--patch-23 * making pristine copy * tree version set tom@example.org--2004/hello--main--1.0
The exact output will vary, but after executing this command, you will have a copy of the latest revision of the hello--main--1.0 branch in the hello directory.
Keeping in sync with the project's changes
Eventually, you will want to see changes made to the project's tree since you got a copy. You can use tla missing to see what changes the project has made since you last updated.
$ tla missing --summary
patch-6
Say "hello" twice.
patch-7
Fix buffer overflow in puts call
patch-8
Fix compiler warnings
Now that you know what patches are missing, it's time to apply them to your tree with tla update.
$ tla update * some output here
Making your own changes and submitting them
When you want to make some changes to your local tree, go ahead and make them. However, if you need to add, remove, or move a file, please read ID-tagging methods first to help tla keep track of this type of change.
Since the project didn't stop changing while you were editing their files, you'll need to sync up every once-in-a-while. You can use tla update, or the almost-equivalent tla replay. The difference is that if there are conflicts update puts your changes in the .rej files, while replay puts the project tree's changes in the .rej files. See ReplayVsUpdate for more details.
Now you've made some changes and want to submit them to the project. First, make sure you've updated to the lastest revision of the project. There are two ways to do this. The first, tla changes only works if you haven't added, removed, or moved any files:
$ tla changes --diffs * looking for tom@example.org--2004/hello--main--1.0--patch-8 to compare with * comparing to tom@example.org--2004/hello--main--1.0--patch-8 M hello.c * modified files --- orig/hello.c +++ mod/hello.c @@ -17,6 +17,8 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * + * New line in copyright notice + * */ #include "hello.h"
As you can see, this is just a unified diff and can be applied with patch -p1. You can also use tla changes --diffs for your own reference to see what you've changed.
The other method is more arch in spirit. You can generate a changeset with tla delta.
$ tla delta tom@example.org--2004/hello--main--1.0--patch-8 hello ,,changes
* finding or making tom@example.org--2004/hello--main--1.0--patch-8
* computing changeset
A hello2.c
M shell/rb-play-order.c
* changeset: ,,changes
$ tla show-changeset --diffs ,,changes
* added files
hello2.c
* modified files
--- orig/hello.c
+++ mod/hello.c
@@ -17,6 +17,8 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*
+ * New line in copyright notice
+ *
*/
#include "hello.h"
$ tar cjvf my-changes.tar.bz2 ,,changes/
,,changes/
,,changes/orig-dirs-index
,,changes/new-files-archive/
,,changes/new-files-archive/hello2.c
,,changes/original-only-dir-metadata
,,changes/removed-files-archive/
,,changes/mod-dirs-index
,,changes/orig-files-index
,,changes/mod-files-index
,,changes/modified-only-dir-metadata
,,changes/patches/
,,changes/patches/hello.c.patch
Then you can email my-changes.tar.bz2 to the maintainer of the project and ask them to commit it.
What if the project is using a config?
Someone please help with this section. I have no experience with configs.
Creating your own branch
Around this point you should think about working through TomLord's arch Meets hello-world, although I hope this section is complete enough that you can get started just using it.
Setting your identity
Before you can create your own branch, you need to set your identity. You do this with the command my-id:
john@shell% tla my-id "John Doe <john@doe.com>"
Arch will remember this (as it will remember your default archive). The identity is used in things like changelog messages.
Creating an archive
Before we can create a branch, we need to set up an archive. This is just a directory on your filesystem in which the revisions of a project are stored. It doesn't have to be on your local file system - you can make an archive on another machine, and access it via HTTP, FTP, SFTP, etc. We'll use a local archive to keep things simple.
If you've used something like CVS before, you can think of the archive as being akin to CVSROOT.
Setting up an archive is fairly straight-forward:
john@shell% tla make-archive john@doe.com--myarchive ~/myarchive john@shell% tla my-default-archive john@doe.com--myarchive
What this does is associates the archive name john@doe.com--myarchive with ~/myarchive, and then sets that archive as the default. It also creates ~/myarchive and puts some control files in there.
Because making a branch is so easy with arch, you tend to accumulate a lot. Many people like to tag their archives with the year so it's easier to rotate them. If you decide to do this, you should emulate the following commands instead:
john@shell% tla make-archive john@doe.com--myarchive-2004 ~/myarchive/2004 john@shell% tla my-default-archive john@doe.com--myarchive-2004
We can verify that this step worked by asking Arch to list the available archives:
john@shell% tla archives
lord@emf.net--2003b
http://arch.quackerhead.com/~lord/archives/lord@emf.net--2003b
john@doe.com--myarchive
/home/john/myarchive
Notice how john@doe--myarchive is not the only archive? The other listed archive is one of the places you can grab the latest version of Arch. We won't be using it in this tutorial.
The archive name is in the form: email@address--archive-name The email address doesn't have to be real - it's just a way of making the archive name unique. Archive names must conform to this convention.
Creating a branch
To set up your own branch of the project, you'll need to use tla archive-setup and tla tag. But, because you've set your archive as the default, you won't have to type its name anymore.
$ tla archive-setup hello--john--1.0
* creating category john@doe.com--myarchive/hello
* creating branch john@doe.com--myarchive/hello--john
* creating version john@doe.com--myarchive/hello--john--1.0
$ tla tag tom@example.org--2004/hello--main--1.0 hello--john--1.0
* made tag john@doe.com--myarchive/hello--john--1.0--base-0 => \
tom@example.org--2004/hello--main--1.0--patch-8
Now when you tla get hello--john--1.0, you'll see the same thing as tom@example.org--2004/hello--main--1.0--patch-8. There is a shortcut using [:Tla Reference/archive-setup:tla archive-setup] -f - -b, but I'll let you look up the details.
Once you've made a batch of changes to your local tree, you'll need to commit them. First, though, you should make a log entry with tla make-log.
$ vim `tla make-log` ** Edit, edit, edit ** $ tla commit * output similar to `tla changes`, with some extra stuff *
A few commits later, you're ready to send your changes off to the project maintainer. But the project has probably also changed.
Keeping your branch up to date
tla star-merge is a magical command that can automatically merge any two related branches. As long as the graph of tags and previous merges looks like a star (no cycles with more than two branches in them), it can even avoid just about all spurious conflicts.
(from a tla get dir of hello--john--1.0) $ tla star-merge -t tom@example.org--2004/hello--main--1.0
This will produce lots of output. Conflicts will be marked with a C in the first column. The conflict files will have diff3-style markers (search for "<<<<") in them.
It's considered good practice to make a star-merge the only thing in a changeset and to commit with tla commit -s 'merged with ...' so that the output of tla log-for-merge winds up in the log.
Making a mirror
To allow the project's maintainer to commit your changes to the main branch, you'll need to set up a mirror of your archive at a publicly available URI. It's still possible to create a changeset with tla delta and submit that, but it's probably easier for all concerned if you just make a mirror.
You use the tla make-archive --mirror command to make a mirror.
$ tla make-archive --listing --mirror john@doe.com--myarchive sftp://server/path/to/webspace
The --listing option creates .listing files that allow tla to deal with the fact that HTTP doesn't provide directory listings. If you're using ftp, you don't need it.
Then use the tla archive-mirror command to copy your archive to your new mirror
$ tla archive-mirror
Give the URI of the mirror and your branch's name to the project maintainer and ask them to commit your changes. And you're done. The maintainer will use star-merge to copy your changes to their archive.
Importing your first project (see Tom's tutorial)
Running your own project can be a significant undertaking, and you should have a good understanding of arch before trying it. TomLord's arch Meets hello-world provides a good tutorial. Don't just read it; work through it.
Common tasks
Getting a list of changes
To list the changes in the archive, you can use the command revisions. tla also offers a command logs, which lists the changes in your working directory. You might find less changes in your working directory than the archive in the case where multiple people are working on the same branch - but we won't get into that here.
These changes descriptions are contained in patch logs. Each patch log looks like an email message, and it stores things like the change description, date, etc. The patch logs are stored both in the archive and in a working directory, so if you're working on some code on your laptop, and don't have access to the archive, you can still list all the changes which have been applied to the tree.
The revisions command looks like:
john@shell% tla revisions --summary
base-0
initial import
patch-1
print hello 5 times instead of 1
Here we demonstrate an extra argument:
john@shell% tla revisions --summary --creator
base-0
John Doe <john@doe.com>
initial import
patch-1
John Doe <john@doe.com>
print hello 5 times instead of 1
Notice the creator name - this is the name we gave to my-id earlier.
Generating a changelog
The patch logs which have been previously mentioned describe more information than we can see using commands like logs or revisions. To access that extra information, tla provides a changelog command:
john@shell% tla changelog
# do not edit -- automatically generated by arch changelog
# arch-tag: automatic-ChangeLog--john@doe.com--myarchive/hello--dev--1.0
#
2003-07-13 09:36:33 GMT John Doe <john@doe.com> patch-1
Summary:
print hello 5 times instead of 1
Revision:
hello--dev--1.0--patch-1
Upon a request from a user, I have made hello print 5 times instead of 1.
You can still obtain the old functionality by running hello | tail -1.
Comments on this change are welcome.
modified files:
./hello.py
2003-07-13 08:58:18 GMT John Doe <john@doe.com> base-0
Summary:
initial import
Revision:
hello--dev--1.0--base-0
(automatically generated log message)
new files:
./hello.py ./world.py
The changelog command accesses the repository to provide the list of changes - so the full list of changes is printed even if your working directory is not up to date.
Getting revisions from the archive
Suppose that John notices that his new version of hello has broken some other program which used it. In order to test that the problem is with John's update, he wants to access a previous release.
He'd start by listing the changes (since he's forgotten):
john@shell% cd
john@shell% tla revisions --summary hello--dev--1.0
base-0
initial import
patch-1
print hello 5 times instead of 1
Notice how the name of the the project is used an argument to the tla revisions command; this is because we moved out of a working directory, so there is no way for tla to guess a default project/branch.
John, from looking at the list, realizes he wants the base version (he might have chosen an earlier patch, had there been more patches to choose from). To get the base-0 release, he can run the following command:
john@shell% tla get hello--dev--1.0--base-0 * from import revision: john@doe.com--myarchive/hello--dev--1.0--base-0 * making pristine copy * tree version set john@doe.com--myarchive/hello--dev--1.0
This creates a directory called hello--dev--1.0--base-0. You can specify an alternative name if you wish:
john@shell% tla get hello--dev--1.0--base-0 mydir
If you want the latest revision, there is a shortcut: you can omit the version specifier (base-0, patch-1, etc), like so:
john@shell% tla get hello--dev--1.0