Glossary

If you're wondering about the definition of a term that's not here, feel free to add the term (in alphabetical order) with "???" as the definition. Feel free to fix the current definitions too.

Arch terms

Archive

Everything in Arch is stored in an archive. This is similar to a repository in CVS. Archives have names of the form:

email-address--short-string
The email address is used to keep archive names globally unique; it does not have to be a real address. The short-string can be related to the purpose of the archive, or a year if you cycle your archive, or both. Some example archive names:

lord@emf.net--2004

Before you can use the contents of an archive, you will need to register it using either a file-path if it's on your local system or a URI if it's a remote archive. Creating an archive with tla make-archive automatically registers it, so you don't need to do so yourself in that case. One reason Arch uses archive names rather than directly using plain URIs, is that this level of indirection allows an archive to be moved without changing all references to it (archive names in arch are embedded in many places). If an archive location changes, users only need to unregister the old location and register the new one, and the rest of the system will continue to work. It also make the archive name simpler to remember an easier to type on the command-line.

Many users like to cycle their archives.

Branch

The second-level of the Arch naming hierarchy within an archive, a branch is a division of an Arch category, and is used to divide the category into parallel lines of development. A fully qualified branch is a string of the form:

archive/category-name--branch-name
In many cases, the archive/ prefix may be omitted, in which case your default archive is used.

For instance, if you have a project my-project, you may have a "main" branch for work on the main version, an "exp" branch for more radical "experimental" changes, and an "i18n" branch for work on internationalizing my-project. In this scenario, you'd have three branches:

my-project--main
my-project--exp
my-project--i18n

A common branch-name used for projects in arch is "devo", for "development" (no known relation to DEVO :-). Names like "devel", "mainline" or "head" are just fine too.

The third level of the Arch naming hierarchy, within each branch, is the version.

Category

The first level of the Arch naming hierarchy within an archive, a category is usually the name of the project. A fully qualified category is a string of the form:

archive/category-name
In many cases, the archive/ prefix may be omitted, in which case your default archive is used.

The second level of the Arch naming hierarchy, within each category, is the branch.

ChangeLog

Can be autogenerated by tla changelog, and will automatically include new revisions' patch logs. A snippet of tla's looks like:

# do not edit -- automatically generated by arch changelog
# arch-tag: automatic-ChangeLog--lord@emf.net--2003b/package-framework--devo--1.0
#
                                                                                                            
2003-12-15 21:18:07 GMT Tom Lord <lord@emf.net> patch-30
                                                                                                            
    Summary:
      verbosify config error message for nonl-diff
    Revision:
      package-framework--devo--1.0--patch-30
                                                                                                            
    verbosify config error message for nonl-diff
                                                                                                            
                                                                                                            
    modified files:
     ChangeLog.d/ChangeLog build-tools/auto-conf-lib/nonl-safe-diff
                                                                                                            
                                                                                                            
2003-12-15 21:09:08 GMT Tom Lord <lord@emf.net> patch-29
                                                                                                            
    Summary:
      fix the diff vs. nonl test for locale insensitivity
    Revision:
      package-framework--devo--1.0--patch-29
                                                                                                            
    fix the diff vs. nonl test for locale insensitivity
                                                                                                            
                                                                                                            
    modified files:
     ChangeLog.d/ChangeLog build-tools/auto-conf-lib/nonl-safe-diff

The generated changelog can be confused when you tag to a new version, so many people use a ChangeLog.d directory containing new changelogs for each version.

Changeset: Basically a diff spread out into a directory. Can track adds, removes, and renames.

Patch Log

Contains information about a single revision. This information includes:

Summary: A one-line summary of the revision's changes
Creator: The id of the person who created the revision
Date: When the revision was created

Revision

The fourth level of the Arch naming hierarchy within an archive, a revision is a division of an Arch version. One is created every time tla commit or tla tag is called. A fully qualified revision is a string of the form:

archive/category-name--branch-name--version-number--revision-name
In many cases, the archive/ prefix may be omitted, in which case your default archive is used. Within a project tree, some commands also allow you to omit the category-name--branch-name--version-number-- prefix, in which case the tree's default version is used.

The revision-name is of the form base-0, patch-n, version-0, or versionfix-n. When a version is first created, the base-0 revision is the first created. Then normal commits and tags create revisions in the patch-n series. n starts at 1 and is incremented for each revision. See Sealing and fixing for details on version-0 and versionfix-n revisions.

A sequence of revisions within a version looks like:

 foo@some.email.net--2004/my-project--devo--0--base-0
 foo@some.email.net--2004/my-project--devo--0--patch-1
 foo@some.email.net--2004/my-project--devo--0--patch-2
 foo@some.email.net--2004/my-project--devo--0--patch-3
 foo@some.email.net--2004/my-project--devo--0--patch-4

Version

The third level of the Arch naming hierarchy within an archive, a version is a division of an Arch branch, and is used to divide the branch into sequential versions. A fully qualified version is a string of the form:

archive/category-name--branch-name--version-number
In many cases, the archive/ prefix may be omitted, in which case your default archive is used.

The version-number should consist entirely of digits and periods (although there's no restriction on the number of periods), e.g. "0", "1.2", or "5.6.2.3.0". Many projects use a separate arch version for each new release, and map the release version directly to the arch version.

Branches that have no real concept of separate versions (for instance, short-lived feature-specific branches) must still use some version number, simply to comply with the Arch syntax. In such a case, you can use something short and simple like "0" (in old projects it's common to see a version like "0.1" used for this purpose -- that's because old versions of arch required version numbers to have two components).

The fourth level of the Arch naming hierarchy, within each version, is the revision.

Editors: Please put an [[Anchor(term)]] just before every term (actually before a horizontal line for readability) so other pages can link to here. It might be a good idea to make subpages (/changeset) for each term. These subpages can just link to their term here until the definition gets uncomfortably long. If other pages link to the subpage instead, their links will be updated transparently. If that wasn't sufficiently clear, ask here and I'll try to clarify.