@need 3200

@node Getting Started with arch
@appendix Getting Started with arch

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


After building and installing @code{arch}, try these steps:

@need 3200

@section Set Your arch User Id

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

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

See @ref{The arch Global Name-space of Users}.




@need 3200

@section Create Your First Archive

Create your own archive with:

@example
@group
        % larch make-archive NAME DIRECTORY
@end group
@group
@end group
@end example

Make that your default archive with:

@example
@group
        % larch my-default-archive NAME
@end group
@group
@end group
@end example

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


See @ref{Archives}.




@need 3200

@section Create Your Revision Library

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


To create a library, simply create an empty directory:

@example
@group
        % mkdir "@{revisions@}"
@end group
@group
@end group
@end example

@noindent
and tell @code{arch} about it:

@example
@group
        % larch my-revision-library "`pwd`/@{revisions@}"
@end group
@group
@end group
@end example

See @ref{Revision Tree Libraries}.




@need 3200

@section 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:

@example
@group
        % mkdir "@{browser@}"
@end group
@group
@end group
@end example

@noindent
and mark that directory as a browser:

@example
@group
        % touch "@{browser@}/=browser"
@end group
@group
@end group
@end example

There is no need to inform @code{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 @ref{arch Web Site Generation Tools}.




@need 3200

@section 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
@geindex notifier
@dfn{notifier}:

@example
@group
        % mkdir @{notify@}
@end group
@group
@end group
@end example
@example
@group
        % cd @{notify@}
@end group
@group
@end group
@end example
@example
@group
        [ edit "=rules.archives" ]
@end group
@group
@end group
@end example

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

@example
@group
        lord@@regexps.com--2002  \
           mail-new-categories:lord \
           mail-new-branches:lord \
           mail-new-versions:lord \
           mail-new-revisions:lord
@end group
@group
@end group
@end example
@example
@group
        lord@@regexps.com--2002 \
          noop:notify-library:lord \
          noop:notify-library:lord \
          noop:notify-library:lord \
          notify-library:lord
@end group
@group
@end group
@end example
@example
@group
        lord@@regexps.com--2002 \
          noop:notify-library:lord \
          noop:notify-library:lord \
          noop:notify-library:lord \
          notify-browser:lord
@end group
@group
@end group
@end example

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:

@example
@group
        % larch my-notifier "`pwd`/@{notify@}
@end group
@group
@end group
@end example

See @ref{arch Triggers} for more information.




@need 3200

@section 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 @geindex docs/examples
@dfn{docs/examples}
directory of distributions of arch.