regexps.com
This and later chapters will show you how to set up and manage a
simple project with arch
through the specific example of a
hello
world
program.
As a first step, you must choose a general category to serve as a name for the project. In the examples, we'll use the name:
hello-world
arch
encourages you to divide up the work on a project into
separate
branches
.
Roughly speaking, branches are a mechanism for splitting the work on a
project into two or more, largely independent efforts. Let's suppose,
for example, that the hello-world
project has two needs:
1) A need to make regular releases of good ol' fashioned hello-world
,
fixing simple bugs, porting the program, and adding tiny features.
2) A need to begin work on a graphical user interface for
hello-world,
which is expected to take about a year to complete.
We'd like those two efforts to proceed in parallel, but not get in each other's way. For example, we don't want GUI code to appear in the regular releases until it is working fairly well.
In such a case, we'll use branches: one for regular releases (the mainline branch) and another for GUI features (the gui branch).
There are many other uses for branches, some of which will be
described later in the manual. For now, we just need one branch: a
branch for the official latest sources of hello-world
, which we'll
call:
hello-world--mainline ^^^^^^^^^^^ ^^^^^^^^ | | | branch name category name
Notice that the category and branch names are separated by two dashes. In general, category and branch names must consist only of letters and dashes, must begin with a letter, must not themselves contain two dashes, and must not end with a dash.
Finally, you must choose a version number for the version of
hello-world
that you'll be working on, and create that version
in the archive.
Version numbers in arch
are not the name of a particular
"snapshot" or release of your project -- though they are related to
that concept. Instead, version numbers are the name of a
development line
: a sequence of changes that you make while creating
a particular release.
In this case, we'll use the name:
hello-world--mainline--0.1 ^^^ | version number
Notice that version numbers are always two positive integers, separated by a period. These are sometimes called the major and minor version.
Having chosen a name, it's time to prepare the archive for use of that name:
% tla archive-setup hello-world--mainline--0.1
After that command, we can query the archive:
% tla categories hello-world
% tla branches hello-world hello-world--mainline
% tla versions hello-world--mainline hello-world--mainline--0.1
People new to arch
are sometimes startled at the rigidity of its
archive structure. Two most common question is:
Why have categories, branches and versions? Why can't I just name my
projects with arbitrary string? These questions are best answered by
recalling that a revision control system is a librarian. Part of
its job is to help people navigate and search through very large
collections of projects and source code. In order to make such
searching practical, arch
defines a cataloging system: categories,
branches, and versions. (See What is Revision Control?.)
This is somewhat analogous to the cataloging systems used in libraries for books, such as the Dewey decimal classification system: it's a hierarchical categorization of everything in the library. It's a uniform way to describe where a given item is stored, and it aids searching by suggesting the relationships between various items. For example, a branch is likely most closely related to other branches in the same category. A version with a higher major version number most likely contains later work than one in the same branch with a lower major version number.
The analogy isn't perfect: book cataloging systems such as Dewey are
based on an official list of categories and subcategories, while
arch
, on the other hand, let's you choose your own category names.
Still, like Dewey, arch
names are based on the idea of grouping
related items together to make them easier to search and navigate.
And just as Dewey is intended to capture the most common patterns of
how people search through books, arch
is intended to capture the
most common patterns of how people search through source archives.
What does the command archive-setup actually do? It
s conceptually
quite simple: it creates new directories in your archive:
% tla whereis-archive lord@emf.net--2003-example /home/lord/{archives}/2003-example % cd `tla whereis-archive lord@emf.net--2003-example`
Categories are top level directories:
% ls =meta-info hello-world
Branches the next level:
% ls hello-world hello-world--mainline
Versions the third:
% ls hello-world/hello-world--mainline hello-world--mainline--0.1
Versions are themselves directories:
% ls hello-world/hello-world--mainline/hello-world--mainline--0.1/ +revision-lock +version-lock
Note: The lock files (e.g. +revision-lock
) are used internally by
arch. When adding new data to an archive, arch
doesn't simply call
mkdir
. Instead, it carefully modifies archives to that they are
always in a consistent state, regardless of what commands are issued
concurrently, or whether or not a command is killed in mid-execution.
regexps.com