The Hackerlab at regexps.com

Starting a New Project

up: arch Meets hello-world
next: Starting a New Source Tree
prev: Creating a New Archive

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.

Create a Project Category

As a first step in the hello-world project, create a new project category in the archive:

        % larch make-category hello-world

You can verify that that worked by asking for a list of all the categories in your archive:

        % larch categories
        hello-world

Create a Project Branch

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 others 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 :

        % larch make-branch 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.

As usual, it's easy to verify that the command worked by asking for a list of branches in the hello-world category:

        % larch branches hello-world
        hello-world--mainline

Choose a Version Number

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.

You start a new development line within a branch as in this example:

        % larch make-version 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.

You can verify the new version by asking what versions exist within your branch:

        % larch versions hello-world--mainline
        hello-world--mainline--0.1

Why is it Like This

People new to arch are sometimes startled at the rigidity of its archive structure. Two common questions (and their answers) are:

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.

Why have two-component version numbers? Some people do not like the limitation of <major>.<minor> version numbers: instead of 0.1 they'd prefer 0.1.1 , for example.

This limitation may, in fact, eventually be removed from arch . For now, though, the uniformity of two-component version numbers makes it easier to sort an arbitrary list of arch version numbers using the standard unix program sort . Ease of integration with standard tools such as sort is a high priority for arch .

How it Works -- Creating Categories, Branches, and Versions

What do the commands make-category , make-branch , and make-version actually do? It's conceptually quite simple: they create new directories in your archive:


        % larch whereis-archive lord@emf.net--2003-example
        /home/lord/{archives}/2003-example

        % cd `larch whereis-archive lord@emf.net--2003-example`

Categories are top level directories:

        % ls
        =meta-info      hello-world

Branches the next level:

        % ls hello-world
        =README         hello-world--mainline

Versions the third:

        % ls hello-world/hello-world--mainline
        =README         hello-world--mainline--0.1

Versions are themselves directories:

        % ls hello-world/hello-world--mainline/hello-world--mainline--0.1/
        +revision-lock  +version-lock   =README

Note: The =README files contain information about who created the category, branch, or revision and when. These are the sole exception to the usual rule that you should never edit files in an archive by hand. You can add new, arbitrary text to those files after the header fields they contain, separated from the headers by a blank line. You should not, however, alter the header fields.

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.

arch Meets hello-world: A Tutorial Introduction to The arch Revision Control System
The Hackerlab at regexps.com