This mini-guide presents a gentle overview of some of Arch's basic features. It is intended as a complement to the Arch tutorial - it may be helpful to read this first, and then move on to other mini-guides, and then the tutorial to learn more. It was initially written by Damien Elmes (web@repose.cx), copied to http://gnuarch.org/bin/view/Main/QuickIntroduction in slightly modified form by AndreasKloeckner on 17 Oct 2003, and finally copied here and modified by JeffreyYasskin on 20 Jan 2004.
Changes made by JeffreyYasskin use tla 1.2_pre0.
Comment to all: It makes sence to remove all these changed-by headers and document all changes/fixes/additions in the comment line of every change, so they are trackable in RecentChanges and do not clutter up the contents. IMHO. -- MikhaelGoikhman
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 a 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 a branch 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 check that the archive was actually registered with 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
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
Cover archive-setup, star-merge, and friends
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
What is changed?
Having imported our project, we can now start to modify it. Imagine that John Doe has modified hello.py to add a brand new feature - printing the string hello 5 times, instead of once. Before commiting his change to the archive, he wants to look over it to make sure it is correct, and he hasn't left any testing code in.
To do this, Arch provides a command called changes:
john@shell% tla changes M ./hello.py
This tells John that hello.py has been modified (M). In order to properly look over the change, John wants to see the difference between the version in the archive and his changes. To do this, he can provide an argument to what-changed:
john@shell% tla changed --diffs M ./hello.py * modified files --- orig/hello.py +++ mod/hello.py @@ -1,3 +1,4 @@ #!/usr/bin/env python -print "hello" +for i in range(5): + print "hello"
This indicates that one line has been removed, and two added.
Note that these commands used a cached copy of the latest archive version, called a pristine tree (pristine, because it is an unmodified version of the latest revision). This is especially useful for disconnected operation - you don't have access to the archive to be able to see what you've changed.
Quick commits
John, happy that his change was as he expected, now wishes to commit his changes back to the archive. To do this, Arch provides a command commit:
john@shell% tla commit -L "print hello 5 times instead of 1"
M ./hello.py
* update pristine tree (john@doe.com--myarchive/hello--dev--1.0--base-0
=> hello--dev--1.0--patch-1)
* commited john@doe.com--myarchive/hello--dev--1.0--patch-1
Note the -L argument. This allows you to specify a log message on the command line. This is useful for quick changes, but sometimes you'll want to have a more detailed log message. To do this, you can create a log message before you commit.
Commiting with a log file
For longer changes, which require a more elaborate change description, it can be useful to create a log message before you go to commit. To do this, you can use Arch's make-log command:
john@shell% tla make-log /home/john/wd/hello/++log.hello--dev--1.0--john@doe.com--myarchive john@shell% cat ++log.hello--dev--1.0--john@doe.com--myarchive Summary: Keywords:
This creates an empty log message, and prints the name of the file. A common idiom is to edit this file as it is created, by doing something like:
john@shell% $EDITOR $(tla make-log) Warning: not overwriting existing log file (editor opens up)
The summary line above is used as a short change description - usually around 60 characters or less. The keywords field isn't used often. Any text below keywords is treated as the body of a log message - it can be as long as you wanted.
John might fill out the log message like so:
Summary: print hello 5 times instead of 1 Keywords: 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.
When John is ready to commit the change, he can just omit the -L argument:
john@shell% tla commit
M ./hello.py
* update pristine tree (john@doe.com--myarchive/hello--dev--1.0--base-0
=> hello--dev--1.0--patch-1)
* commited john@doe.com--myarchive/hello--dev--1.0--patch-1
Getting a list of changes
To list the changes in the archive, you can use the command revisions. Arch 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, Arch 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 provided to revisions. This is because we moved out of a working directory - so there is no associated project.
John, from looking at the list, realises 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
-- AndreasKloeckner - 17 Oct 2003