A work in progress by Joshua Haberman
A branch is a line of development. It begins with a base revision and can undergo changes through time. A branch has a name of the form category--branchname--version. An example is audacity--mainline--1.3. The hierarchy is intended for humans, and is not significant to the software.
Work is committed to a branch in the form of a changeset. A changeset can change the contents of an arbitrary number of files, move files, change permissions, etc. all within a single changeset. The state of the tree after a particular changeset is called a revision. A revision can be appended to the branch name to refer to that particular revision on the branch, for example audacity--mainline--1.3--patch-1.
In the diagram below, the triangles represent changesets (think of greek delta) and the rectangles represent revisions. Note that there is a bit of ambiguity: patch-1 is the name of the changeset that takes the tree to the patch-1 revision.
The data for a branch lives in an archive, which is physically a directory tree that resides on a computer somewhere. An archive is roughly equivalent to a CVS repository. Archives have names of the form emailaddress--archive-name. An example is joshua@haberman.com--2003. The archive name usually has a year in it, because archives grow as they acquire more revision history; the year allows everyone to move to a new archive every so often so that archives don't grow too large.
An archive can contain an arbitrary number of branches. The combination of archive name and branch name creates a globally unique identifier for a particular branch, for example: joshua@haberman.com--2003/audacity--mainline--1.3. Add a revision name to this, and you have a globally unique identifier for a particular snapshot of a particular branch: joshua@haberman.com--2003/audacity--mainline--1.3--patch-15.
A developer can create a working directory (or "working tree") of a particular branch on their development workstation by using the get operation on an archive and branch. This working tree contains all of the versioned files plus metadata about the branch that is stored in an {arch} directory.
Developers can access the archive over the local filesystem, SFTP, FTP, or HTTP extended with WebDAV. No intelligence is required on the server; the client reads and writes the files of the archive directly.
If the developer has write-access to the archive, he/she can commit changesets to the branch (creating new revision) using the commit operation.
If someone else commits a changeset to the branch after you have obtained a working tree, then your tree is missing changes that exist on the branch; your tree is said to be out of date. There are two operations that can bring your tree up to date: update and replay. If you have not made any local changes, the two methods are equivalent. If you have made local changes, they two methods differ in how they attempt to merge your local changes with the repository's changes.
Replay is simpler. It retrieves all unapplied changesets in order and applies them sequentially to your local, modified tree. If there are conflicts, the changes from the archive that conflict are rejected (the changes are placed in .rej files).
Replay causes local changes to be given precedence over changes in the branch, since conflicts cause the branch's changes to be rejected. Update does the opposite: it gives the repository changes precedence. It works by adding an extra step; first it undoes your local changes, then applies the changesets necessary to bring your tree up to date, then tries to re-apply your local changes, rejecting whatever changes conflict.
These are the basic operations that apply to single-branch development. The techniques explained up to this point allow you to use what is often called the update/commit style of cooperation. There is only one branch that is shared by all of the project's contributors.
This model is limiting for all but the simplest of projects. The power of Arch comes from the ease with which you can have parallel lines of development.