@need 3200

@node Creating a New Archive
@chapter Creating a New Archive

An archive is a dedicated directory which @code{arch} uses to hold a
library of your project trees and changesets.  This chapter shows you
how to create a new archive.

@need 3200

@section Choose a Location

You need to decide where to store your archive: where to create the
directory that will contain the archive.


@strong{Usage Advice:} It is likely that you'll eventually want to have @emph{more
than one} archive.  Therefore, it is a good idea to create a directory
of archives.


In the examples that follow, we'll be creating an archive as a
subdirectory of @code{~/@{archives@}}, a directory of archives.

@example
@group
        # Create a directory in which to store archives:
        #
        % mkdir ~/@{archives@}
@end group
@group
@end group
@end example



@need 3200

@section Choose an Archive Name

Next, you need to choose a name for your archive.  An archive name
consists of an email address, followed by two dashes (@code{--}), followed
by a suffix.  By convention, the email address should be that of the
archive owner.


In the example, we'll use the name:

@example
@group
        lord@@emf.net--2003-example
@end group
@group
@end group
@end example

@strong{Usage Advice:} If you use a single archive for a very long time it
will eventually accumulate a very large amount of data and thus start
to become inconvenient to work with.  Because @code{arch} seamlessly
operates across archive boundaries, there is no need to keep
everything in just one archive.  It's a good idea to plan to divide up
your archives by @emph{time} and that suggests that you include a date in
the archive name.  In the example above, the archive is labeled @code{2003}:
a year later, we could create @code{lord@@emf.net--2004-example} and
continue the project in that new archive.  The @code{2003} archive will
still exist at that point -- we'll just stop adding new data to it.


@strong{Usage Advice:} You should plan on having multiple archives, and
therefore choose archive names that distinguish them.  The suffix
@code{-example} above tells us that this archive is being created just work
through the examples in this tutorial.




@need 3200

@section Create the Archive

@geindex make-archive



To create a new archive, use the @code{make-archive} command, telling it
the archive name and archive location:

@example
@group
        # Create the new archive
        # 
        % larch make-archive lord@@emf.net--2003-example \
                             ~/@{archives@}/2003-example
@end group
@group
@end group
@end example



@need 3200

@section Make this Your Default Archive

@geindex my-default-archive



To save yourself from having to type the archive name to every future
command, declare that your new archive is your default choice:

@example
@group
        # Choose a default archive
        # 
        % larch my-default-archive lord@@emf.net--2003-example
        default archive set (lord@@emf.net--2003-example)
@end group
@group
@end group
@end example

Your current default is reported by:

@example
@group
        % larch my-default-archive
        lord@@emf.net--2003-example
@end group
@group
@end group
@end example

And you can cancel the default setting with:

@example
@group
        % larch my-default-archive -d
        user default archive removed
@end group
@group
@end group
@end example

(If you experiment with @code{-d}, be sure to re-establish your default
archive so that you can continue to follow the examples.)




@need 3200

@section How it Works -- New Archives

@geindex whereis-archive

@geindex archives



Let's examine what that command did.


First, @code{larch} now knows about the new archive:

@example
@group

@end group
@group
        # What archives does `larch' know about?
        # 
        % larch archives
        lord@@emf.net--2003-example
                /home/lord/@{archives@}/2003-example
@end group
@group

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


@end group
@group
        # Where is that data stored?
        # 
        % ls ~/.arch-params
        =default-archive        =id             =locations
@end group
@group

@end group
@group
        % cat ~/.arch-params/=default-archive
        lord@@emf.net--2003-example
@end group
@group

@end group
@group
        % ls ~/.arch-params/=locations
        lord@@emf.net--2003-example
@end group
@group

@end group
@group
        % cat ~/.arch-params/=locations/lord@@emf.net--2003-example
        /home/lord/@{archives@}/2003-example
@end group
@group

@end group
@end example

Next, the archive directory has been created and contains a few files:

@example
@group

@end group
@group
        % ls ~/@{archives@}
        2003-example
@end group
@group

@end group
@group
        % ls -a ~/@{archives@}/2003-example
        .                       .archive-version
        ..                      =meta-info
@end group
@group

@end group
@group
        % cat ~/@{archives@}/2003-example/.archive-version
        Hackerlab arch archive directory, format version 1.
@end group
@group

@end group
@group
        % ls -a ~/@{archives@}/2003-example/=meta-info/
        .       ..      name
@end group
@group

@end group
@group
        % cat ~/@{archives@}/2003-example/=meta-info/name
        lord@@emf.net--2003-example
@end group
@group

@end group
@end example

@strong{Caution:} You should not edit files in @code{~/.arch-params/} or files in
an archive "by hand."







