@need 3200

@node Archives
@chapter Archives

@geindex archives (the concept)



This chapter discusses @geindex archives
@dfn{archives} -- places where revisions can stored
and shared.  Archives are used to keep a detailed history of how a
project evolves.  They are used to help a team of developers stay "in
sync" -- in agreement about what the official, latest revision of a
project really is.  Archives are used to help coordinate divergent
development paths (branches) and to merge changes between branches.

@need 3200

@section Archive Names Revisited

Every archive has a name which @emph{should} be globally unique.  These
names were previously introduced in the context of project names
generally (see @ref{Archive Names}.)


To briefly review, 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
will be globally unique.  Here is an example:

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



@need 3200

@section Creating a New Archive

@geindex make-archive



To create a new archive on a local file system, use the @code{make-archive}
command:

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

The @code{NAME} is the name for the archive.  The @code{LOCATION} is a name for
a directory that will be created to hold the archive.  For example:

@example
@group
        % larch make-archive \
               joe.hacker@@gnu.org--test-archive \
               ~/@{test-archive@}
@end group
@group
@end group
@end example



@need 3200

@section Mapping Archive Names to Locations

@geindex archives (the command)

@geindex register-archive

@geindex whereis-archive



@code{arch} maintains a mapping of archive names to archive locations
separately for each user, in the directory @code{~/.arch-params}.


You can see the list of archives for which you have a recorded
location by using the @code{archives} command, as in this example:

@example
@group
        % larch archives
        joe.hacker@@gnu.org--test-archive
                /home/joe/@{test-archive@}
@end group
@group
@end group
@end example

The command @code{register-archive} is used to add, remove, or update the
location of an archive:

@example
@group
        % larch register-archive ARCHIVE-NAME LOCATION
@end group
@group
@end group
@end example

@noindent
records a new archive location or changes an old one.  The command:

@example
@group
        % larch register-archive -d ARCHIVE-NAME
@end group
@group
@end group
@end example

@noindent
removes the record of an archive location.


If you want to know the registered location of a particular archive,
you can use:

@example
@group
        % larch whereis-archive ARCHIVE-NAME
        LOCATION
@end group
@group
@end group
@end example



@need 3200

@section Remote Archives

@geindex remote archives

@geindex ftp access to archives



If an archive directory is accessible via @code{FTP}, then @code{arch} can
access that archive remotely, simply by specifying an FTP URI for the
archive's location:

@example
@group
        % larch register-archive joe.hacker@@gnu.org--test-archive \
                ftp://anonymous@@ftp.gnu.org/users/joe/@{test-archive@}
@end group
@group
@end group
@end example

The URI can include a password.  When @code{arch} saves a location in your
@code{.arch-params} directory, it is made unreadable to anyone but you --
weak security, but security nonetheless.




@need 3200

@section Your Default Archive

Using @code{arch} is generally simplified by setting a @geindex default archive
@dfn{default archive} --
the archive to use by default when no other is specified.


The command:

@example
@group
        % larch my-default-archive [options] [archive]
@end group
@group
@end group
@end example

@noindent
can be used to set or check your default archive.  (This command was
previously introduced.  See @ref{Archive Names}.)


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

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






