The Hackerlab at `regexps.com`

## The arch Global Name-space of Projects

up: arch next: Archives prev: The arch Global Name-space of Users

Another central organizing concept of `arch` is a global namespace of projects.

This chapter describes how projects are named, and how the names are applied to project trees.

- The Structure of Project Names
- Archive Names
- Category Names and Branch Labels
- Version Numbers
- Labelling Project Trees
- Combining Project Trees

### The Structure of Project Names

up: The arch Global Name-space of Projects next: Archive Names

The `arch` project name-space is designed to reflect the intricacies of how projects evolve in the real world. For example, two or more different organizations may separately develop and distribute a given project. A project can split into multiple development paths. Each path typically evolves through a series of versions. `arch` provides a way to precisely name all of these different instances of a given project.

An `arch` project name has four basic parts, introduced here, and explained in detail below.

An Archive Name The archive name identifies the organization that distributes particular versions of a project. Some example archive names might be:

            hackerlab@regexps.com--hackerlab
            hurd@gnu.org--hurd-team

The Category Name The category name is a generic name for the project. It is what people usually think of as a "project name". Some example category names are:

            arch
            gcc
            rx

The Branch Label When a project splits into multiple development paths (even if only temporarilly -- as a convenience to the maintainers), each path is given a branch label . Some example branch labels are:

            development
            experimental

The Version Number `arch` uses fairly simple version numbers , consisting of a major and minor version number:

            1.2
            2.0

The four parts of a project name fit together this way:

            <archive-name>/<category>[--<branch-label>]--<version-number>

As in the example:

       hackerlab@regexps.com--hackerlab/arch--development--2.0
                            ^            ^         ^        ^
                            |            |         |        |
                      archive name    category   branch    version
                                                 label

Notice that the archive name is separated from the rest of the project name by `/` . The other parts of the project name are separated by `--` .

When you use `arch` , you often abbreviate project names. For example, you can leave off the archive name and a default archive will be presumed:

            arch--development--2.0

or you can leave off the version number and, depending on context, that means either "the latest version" or "all versions":

            arch--development

If you have one branch which is "primary branch", you can leave out the branch label:

            arch--2.0
            hackerlab@regexps.com--hackerlab/arch--2.0
            arch
            hackerlab@regexps.com--hackerlab/arch

Those last two names are also sometimes used to mean "every branch of arch" or "every branch of arch at the hackerlab archive", respectively.

### Archive Names

up: The arch Global Name-space of Projects next: Category Names and Branch Labels prev: The Structure of Project Names

An archive name designates an organization that develops and/or distributes software. Archive names should be globally unique.

Later in the manual, we'll see that archive names are specifically used to identify revision control archives.

An archive name consists of an email address (with complete hostname), followed by -- , followed by an additional string of numbers, letters and dashes. Choose an email address which is exclusively yours (or your project's). That way, your archive name(s) will be globally unique. Here is an example:

                    joe.hacker@gnu.org--test-archive

If your organization is going to have more than one revision control archive, you'll use more than one archive name:

                    joe.hacker@gnu.org--gcc-archive
                    joe.hacker@gnu.org--guile-archive
                    joe.hacker@gnu.org--2001

You can choose an archive name to use as the default for all `arch` commands. When you run a command without explicitly specifying a archive, the default is used:

            % larch my-default-archive joe.hacker@gnu.org--2001

To find out the current default:

            % larch my-default-archive
            joe.hacker@gnu.org--2001

In general, `arch` sub-commands accept the option `-A` to specify a non-default archive:

            % larch my-default-archive -A joe.hacker@gnu.org--test-archive
            joe.hacker@gnu.org--test-archive

### Category Names and Branch Labels

up: The arch Global Name-space of Projects next: Version Numbers prev: Archive Names

The category of a project name identifies, generally, what the project is. The category is the same no matter who is distributing the project, or which development path is being considered.

The branch label is optional. It can be used to distinguish alternative development paths for a given project.

The category and branch label must match the regexp:

            [[:alpha:]]([[:alnum:]]*(-[[:alnum:]]+)?)*

or in other words, they must begin with a letter and consist entirely of digits, letters, and dashes -- but must not contain two dashes in a row, and must not end with a dash.

### Version Numbers

up: The arch Global Name-space of Projects next: Labelling Project Trees prev: Category Names and Branch Labels

In a somewhat arbitrary but extremely traditional way, branches are divided into a series of versions.

The version number must match the regexp:

            [[:digit:]]+\\.[[:digit:]]+

or in other words, it must consist of two strings of digits, separated by a single period. The first string of digits is called the major version number and the second string of digits is called the minor version number .

Note: Version numbers are not revision numbers. In other words, when the `arch` revision control system stores multiple snapshots of the development of your project, it does not assign a new version number to each snapshot. Instead, each project version is further subdivided into something called "patch levels", which are explained in detail later in the manual.

### Labelling Project Trees

up: The arch Global Name-space of Projects next: Combining Project Trees prev: Version Numbers

Every project tree may be labeled with a project name using the `set-tree-version` command, as in this example:

            % cd ~/wd/arch
            % larch set-tree-version arch--1.0

That project name becomes the default for `arch` operations within that tree.

You can find out the project name of a tree with `tree-version` :

            % larch tree-version
            joe.hacker@gnu.org--2001/arch--1.0

Notice that `arch` used the default archive (returned by `my-default-archive` ) when `set-tree-version` was invoked. You can also specify an archive explicitly, as in these two examples:

            % larch set-tree-version joe.hacker@gnu.org--alt/arch--1.0

or

            % larch set-tree-version -A joe.hacker@gnu.org--alt arch--1.0

### Combining Project Trees

up: The arch Global Name-space of Projects prev: Labelling Project Trees

You can, in fact, combine project trees: storing the files and directories from multiple projects under a common root. This can be useful if you have separately maintained projects that, nevertheless, are tightly integrated. This is explained in a later chapter (xref!!!).

arch: The arch Revision Control System
The Hackerlab at `regexps.com`