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.
As you should recall, an archive has both a logical name, and a physical location:
% tla archives email@example.com ^^^^^^^^^^^^^^^^^^^^^^^^^^ | /usr/lord/archives/2003-example | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | | | archive location | archive name
(See Creating a New Archive.)
Some archives can be accessed over a network, currently via any of the protocols:
FTP SFTP WebDAV plain HTTP
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:
% tla register-archive firstname.lastname@example.org \ http://email@example.com
or an FTP archive:
% tla register-archive firstname.lastname@example.org \ ftp://email@example.com
You can see that these commands have taken effect:
% tla archives firstname.lastname@example.org http://email@example.com firstname.lastname@example.org /usr/lord/examples/archives/2003-example email@example.com ftp://firstname.lastname@example.org
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:
% tla my-default-archive email@example.com % tla categories [...categories in the remote archive...]
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:
% tla my-default-archive firstname.lastname@example.org
There are two other ways to access a remote archive:
Every command that operates on archives accepts a
-A option which
can be used to override the default:
% tla my-default-archive email@example.com % tla categories -A firstname.lastname@example.org [... categories in email@example.com ...]
Usage Note: A
-A argument takes precedence over your default
archive but is overridden by fully qualified project names (see
Commands that accept project names allow you to use project names fully qualified project names. A fully qualified name is formed by prefixing an archive name, followed by a slash, to the project name:
category name: tla => firstname.lastname@example.org/tla branch name: tla--devo => email@example.com/arch--tla version name: tla--devo--1.0 => firstname.lastname@example.org/tla--devo--1.0 revision name: tla--devo--1.0--patch-1 => email@example.com/tla--devo--1.0--patch-1
As in this example:
% tla my-default-archive firstname.lastname@example.org % tla branches email@example.com/hello-world [... branches of hello-world in firstname.lastname@example.org ...]
Usage Note: A fully qualified name takes precedence over both
arguments and your default archive.
Operating system and server access controls can be used to limit some or all users to read-only access. For example, FTP is usually configured in such a way that anonymous users can read, but not modify the archive.
A 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).
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
are three steps (suppose $remote_location is something like
First, register the remote archive under a pseudonum, formed by
-SOURCE to it's name:
% tla register-archive email@example.com-SOURCE $remote_location
Second, create your local mirror:
% tla make-archive --mirror-from firstname.lastname@example.org-SOURCE $local_location
That command will, as a side effect, register
the name of your local mirror.
Finally, copy data from the remote archive:
% tla archive-mirror email@example.com
Whenever the remote archive has been added to, you can incrementally
update your mirror by repeating the
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.
Let's suppose that you have a local archive
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
firstname.lastname@example.org registered, you
can create the remote mirror with:
% tla make-archive --mirror email@example.com $remote_location
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:
% tla archive-mirror firstname.lastname@example.org
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:
% tla make-archive --listing --mirror email@example.com \ $remote_location
--listing flag causes arch to keep
.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
.listing files to fall out of date
(for example, if you kill an
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:
% tla archive-fixup firstname.lastname@example.org-MIRROR
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:
% tla make-archive $archive_name $remote_location
or, to create a remote repository with .listing files:
% tla make-archive --listing $archive_name $remote_location
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