@need 3200

@node Shared and Public Archives
@chapter Shared and Public Archives

In the earlier chapters, you learned how to create your first archive,
start a project, check in the initial sources and subsequent changes,
and retrieve past revisions.


In this chapter you'll learn how to make an archive available over a
network and begin to learn how multiple programmers can share a single
archive.

@need 3200

@section Registering for Network Access to Archives

As you should recall, an archive has both a logical name, and a
physical location:

@example
@group
        % tla archives
        lord@@emf.net--2003-example
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
          |     /usr/lord/@{archives@}/2003-example
          |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          |                     |
          |              archive location        
          |
        archive name
@end group
@group
@end group
@end example

(See @ref{Creating a New Archive}.)


Some archives can be accessed over a network, currently via any
of the protocols:

@example
@group
        FTP
        SFTP
        WebDAV
        plain HTTP
@end group
@group
@end group
@end example

Later in this chapter, you'll learn how to create such archives.


For now, you should know that to access such an archive, you register
it's name and physical location, using a URL for the physical
location.


For example, to access an HTTP or WebDAV archive:

@example
@group
    % tla register-archive lord@@emf.net--2003b \
            http://regexps.srparish.net/@{archives@}/lord@@emf.net--2003b
@end group
@group
@end group
@end example

@noindent
or an FTP archive:

@example
@group
    % tla register-archive lord@@regexps.com--2002 \
            ftp://ftp.regexps.com/@{archives@}/lord@@regexps.com--2002
@end group
@group
@end group
@end example

You can see that these commands have taken effect:

@example
@group
    % tla archives
    lord@@emf.net--2003b
            http://regexps.srparish.net/@{archives@}/lord@@emf.net--2003b
    lord@@emf.net--2003-example
            /usr/lord/examples/@{archives@}/2003-example
    lord@@regexps.com--2002
            ftp://ftp.regexps.com/@{archives@}/lord@@regexps.com--2002
@end group
@group
@end group
@end example



@need 3200

@section Working with Several Archives at Once

After you've registered additional archives, how do you access them?


One trivial way is to make the archive you are interested in your
default:

@example
@group

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

@end group
@group
        % tla categories
        [...categories in the remote archive...]
@end group
@group

@end group
@end example

It can, of course, be inconvenient to keep changing your default
archive.  So for now, let's restore it to the archive we've been
using in the examples:

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

There are two other ways to access a remote archive:

@need 3200

@subsection Selecting an Archive with -A

Every command that operates on archives accepts a @code{-A} option which
can be used to override the default:

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

@end group
@group
        % tla categories -A lord@@emf.net--2003
        [... categories in lord@@emf.net--2003 ...]
@end group
@group

@end group
@end example

@strong{Usage Note:} A @code{-A} argument takes precedence over your default
archive but is overridden by fully qualified project names (see
below).




@need 3200

@subsection Fully Qualified Project Names

Commands that accept project names allow you to use @geindex fully qualified
project names
@dfn{fully qualified
project names}.   A fully qualified name is formed by prefixing an
archive name, followed by a slash, to the project name:

@example
@group
   category name:
   tla                     => lord@@emf.net--2003/tla
@end group
@group

@end group
@group
   branch name:
   tla--devo               => lord@@emf.net--2003/arch--tla
@end group
@group

@end group
@group
   version name:
   tla--devo--1.0          => lord@@emf.net--2003/tla--devo--1.0
@end group
@group

@end group
@group
   revision name:
   tla--devo--1.0--patch-1 => lord@@emf.net--2003/tla--devo--1.0--patch-1
@end group
@group

@end group
@end example

As in this example:

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

@end group
@group
        % tla branches lord@@emf.net--2003/hello-world
        [... branches of hello-world in lord@@emf.net--2003 ...]
@end group
@group

@end group
@end example

@strong{Usage Note:} A fully qualified name takes precedence over both @code{-A}
arguments and your default archive.







@need 3200

@section Read-only Archives

Operating system and server access controls can be used to limit some
or all users to @emph{read-only} access.  For example, FTP is usually
configured in such a way that anonymous users can read, but not modify
the archive.




@need 3200

@section Creating Local Mirrors, Remote Mirrors, and Remote Archives

A @geindex mirror
@dfn{mirror} is an archive whose contents are copied from another
archive.   You can not commit to a mirror in the ordinary way, you can
only update it's copy of it's source.


There are two primary uses for mirror archives:  one is to make a
local copy of a remote mirror (so that it's contents can be accessed
without going over a network);   the other is to make a remote copy of
a local archive (so that others can access that copy).

@need 3200

@subsection Mirroring a Remote Archive Locally

Let's suppose that, in order to have the fastest possible access to
it, or to be able to use it while disconnected, you want to mirror a
remote archive locally rather than accessing it over network.


Supposing that you wanted to do this with @code{lord@@emf.net--2003b}, there
are three steps (suppose $remote_location is something like 
http://my.site.com//archives/lord@@emf.net--2003b).


First, register the remote archive under a pseudonum, formed by
appending @code{-SOURCE} to it's name:

@example
@group
        % tla register-archive lord@@emf.net--2003b-SOURCE $remote_location
@end group
@group
@end group
@end example

Second, create your local mirror:

@example
@group
        % tla make-archive --mirror-from lord@@emf.net--2003b-SOURCE $local_location
@end group
@group
@end group
@end example

That command will, as a side effect, register @code{lord@@emf.net--2003b} as
the name of your local mirror.


Finally, copy data from the remote archive:

@example
@group
        % tla archive-mirror lord@@emf.net--2003b
@end group
@group
@end group
@end example

Whenever the remote archive has been added to, you can incrementally
update your mirror by repeating the @code{tla archive-mirror} step.


If you don't want to mirror the entire archive, you can optionally
limit the mirror to specific categories, branches, or versions. See
tla archive-mirror -H for more.




@need 3200

@subsection Mirroring a Local Archive Remotely

Let's suppose that you have a local archive @code{mine@@somewhere.com}, and
you'd like to "publish" a mirror of that archive on the Internet
so that other people can read from it.


Assuming that you already have @code{mine@@somewhere.com} registered, you
can create the remote mirror with:

@example
@group
        % tla make-archive --mirror mine@@somewhere.com $remote_location
@end group
@group
@end group
@end example

Arch will write directly to $remote_location, so it must be a writeable
transport such as sftp, and not something such as standard http.


You can initialize or incrementally update the contents of the remote
mirror with:

@example
@group
        % tla archive-mirror mine@@somewhere.com
@end group
@group
@end group
@end example

One common situation for many people is that they are able to 
install static files as part of a web site, but they can't provide
WebDAV access to that web site.   Even under those conditions you can
still publish an arch archive, though there are two subtleties.


First, when running make-archive, you need to provide an extra flag:

@example
@group
        % tla make-archive --listing --mirror mine@@somewhere.com \
                        $remote_location
@end group
@group
@end group
@end example

The @code{--listing} flag causes arch to keep @code{.listing} files up-to-date
in the mirror, and that, in turn, allows people to read from the
archive using arch over vanilla HTTP (sans WebDAV support).


Second, it _is_ possible for the @code{.listing} files to fall out of date
(for example, if you kill an @code{archive-mirror} command at just the
right time_.   If you know or suspect that has occurred, you can repair
the archive in question by running archive-fixup as in this example:

@example
@group
        % tla archive-fixup mine@@somewhere.com-MIRROR
@end group
@group
@end group
@end example



@need 3200

@subsection Making a Remote Repository

Although mirroring is a common use of remote repositories, it is
possible to create remote repositories which are not mirrors, and then
to commit to those directly.   


One can create a remote repository with a command such as:

@example
@group
        % tla make-archive $archive_name $remote_location
@end group
@group
@end group
@end example

@noindent
or, to create a remote repository with .listing files:

@example
@group
        % tla make-archive --listing $archive_name $remote_location
@end group
@group
@end group
@end example






@need 3200

@section Mixing Access Modes

There is nothing to prevent you from making a single archive available
via multiple access methods.   For example, you can register an FTP
accessible archive using a local-filesystem location on the machine
that contains the FTP directory, but ask other users to register it
with an @code{ftp:} URL.







