The Hackerlab at regexps.com

Getting Started with arch

up: arch
next: Implementing Development Policies

Here is a whirlwind guide to getting started with arch . This appendix presumes that you are familiar with the material in previous chapters.

After building and installing arch , try these steps:

Set Your arch User Id

The first step is to set your id with a command like:

        % larch my-id "Jane Hacker <jane.hacker@gnu.org>"

See The arch Global Name-space of Users.

Create Your First Archive

Create your own archive with:

        % larch make-archive NAME DIRECTORY

Make that your default archive with:

        % larch my-default-archive NAME

You might want to edit the top-level =README file in your archive to describe what you intend to store there. Editting =README files is one of the few exceptions to the rule that you should never modify files in the archive "by hand".

See Archives.

Create Your Revision Library

Revision libraries are strictly optional, but they are desirable if you want to obtain the best performance from arch or use all of the available features.

To create a library, simply create an empty directory:

        % mkdir "{revisions}"

and tell arch about it:

        % larch my-revision-library "`pwd`/{revisions}"

See Revision Tree Libraries.

Set Up Your Revision Browser

If you want to be able to browse change sets and past revisions with a web browser, you need to set up a browser directory.

Create an empty directory:

        % mkdir "{browser}"

and mark that directory as a browser:

        % touch "{browser}/=browser"

There is no need to inform arch of the location of your browser at this step -- that will come later when you set up a "notifier" which updates the browser.

See arch Web Site Generation Tools.

Set Up Notifiers

If you want your library and browser to be updated automatically as you commit revisions to the repository, you need to set up a notifier :

        % mkdir {notify}

        % cd {notify}

        [ edit "=rules.archives" ]

As an example of the format of =rules.archives , here is the one I use. In the documentation, long lines have been broken up with continuation markers (\ ), but in the real file, they are just very long lines:

        lord@regexps.com--2002  \
           mail-new-categories:lord \
           mail-new-branches:lord \
           mail-new-versions:lord \
           mail-new-revisions:lord

        lord@regexps.com--2002 \
          noop:notify-library:lord \
          noop:notify-library:lord \
          noop:notify-library:lord \
          notify-library:lord

        lord@regexps.com--2002 \
          noop:notify-library:lord \
          noop:notify-library:lord \
          noop:notify-library:lord \
          notify-browser:lord

The first line defines rules for sending email when new revisions are committed, or when categories, branches, or versions are created.. The second line updates the revision library when new revisions are added to the library. The third line updates the browser whe new revisions are added.

Having set up your notifier directory, inform arch:

        % larch my-notifier "`pwd`/{notify}

See arch Triggers for more information.

Get to Work

Now you can create branches from other archives, import your own original projects, and otherwise use the various commands documented in this manual.

Additional step by step directions can be found in the docs/examples directory of distributions of arch.

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