@need 3200

@node The arch Global Name-space of Projects
@chapter The arch Global Name-space of Projects

Another central organizing concept of @code{arch} is a global namespace of
projects.


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

@menu
* The Structure of Project Names::
* Archive Names::
* Category Names and Branch Labels::
* Version Numbers::
* Labelling Project Trees::
* Combining Project Trees::
@end menu

@need 3200

@node The Structure of Project Names
@section The Structure of Project Names

The @code{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.  @code{arch} provides
a way to precisely name all of these different instances of a given
project.


An @code{arch} project name has four basic parts, introduced here, and
explained in detail below.


@strong{An Archive Name} The @geindex archive name
@dfn{archive name} identifies the organization that
distributes particular versions of a project.  Some example archive
names might be:

@example
@group
        hackerlab@@regexps.com--hackerlab
        hurd@@gnu.org--hurd-team
@end group
@group
@end group
@end example

@strong{The Category Name} The @geindex category name
@dfn{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:

@example
@group
        arch
        gcc
        rx
@end group
@group
@end group
@end example

@strong{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 @geindex branch label
@dfn{branch label}.  Some example
branch labels are:

@example
@group
        development
        experimental
@end group
@group
@end group
@end example

@strong{The Version Number} @code{arch} uses fairly simple @geindex version numbers
@dfn{version numbers},
consisting of a major and minor version number:

@example
@group
        1.2
        2.0
@end group
@group
@end group
@end example

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

@example
@group
        <archive-name>/<category>[--<branch-label>]--<version-number>
@end group
@group
@end group
@end example

As in the example:

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

Notice that the archive name is separated from the rest of the project
name by @code{/}.  The other parts of the project name are separated by
@code{--}.


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

@example
@group
        arch--development--2.0
@end group
@group
@end group
@end example

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

@example
@group
        arch--development
@end group
@group
@end group
@end example

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

@example
@group
        arch--2.0
        hackerlab@@regexps.com--hackerlab/arch--2.0
        arch
        hackerlab@@regexps.com--hackerlab/arch
@end group
@group
@end group
@end example

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




@need 3200

@node Archive Names
@section Archive Names

@geindex my-default-archive



An @geindex archive name
@dfn{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 @geindex --
@dfn{--}, 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:

@example
@group
                joe.hacker@@gnu.org--test-archive
@end group
@group
@end group
@end example

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

@example
@group
                joe.hacker@@gnu.org--gcc-archive
                joe.hacker@@gnu.org--guile-archive
                joe.hacker@@gnu.org--2001
@end group
@group
@end group
@end example

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

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

To find out the current default:

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

In general, @code{arch} sub-commands accept the option @code{-A} to specify a
non-default archive:

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



@need 3200

@node Category Names and Branch Labels
@section Category Names and Branch Labels

The @geindex category
@dfn{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 @geindex branch label
@dfn{branch label} is optional.  It can be used to distinguish
alternative development paths for a given project.


The @geindex category
@dfn{category} and @geindex branch label
@dfn{branch label} must match the regexp:

@example
@group
        [[:alpha:]]([[:alnum:]]*(-[[:alnum:]]+)?)*
@end group
@group
@end group
@end example

@noindent
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.




@need 3200

@node Version Numbers
@section Version Numbers

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


The @geindex version number
@dfn{version number} must match the regexp:

@example
@group
        [[:digit:]]+\\.[[:digit:]]+
@end group
@group
@end group
@end example

@noindent
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 @geindex major
version number
@dfn{major
version number} and the second string of digits is called the @geindex minor
version number
@dfn{minor
version number}.


@strong{Note:} @emph{Version numbers} are not @emph{revision numbers}.  In other words,
when the @code{arch} revision control system stores multiple snapshots of
the development of your project, it does @emph{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.




@need 3200

@node Labelling Project Trees
@section Labelling Project Trees

@geindex set-tree-version

@geindex tree-version



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

@example
@group
        % cd ~/wd/arch
        % larch set-tree-version arch--1.0
@end group
@group
@end group
@end example

That project name becomes the default for @code{arch} operations within
that tree.


You can find out the project name of a tree with @code{tree-version}:

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

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

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

@noindent
or

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



@need 3200

@node Combining Project Trees
@section Combining 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!!!).







