The Hackerlab at regexps.com

Shared and Public Archives

up: arch Meets hello-world
next: The update/commit Style of Cooperation
prev: Retrieving Earlier Revisions

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.

Registering for Network Access to Archives

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

        % larch archives
        lord@emf.net--2003-example
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
          |     /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:

    % larch register-archive lord@emf.net--2003 \
            http://regexps.srparish.net/{archives}/lord@emf.net--2003

or an FTP archive:

    % larch register-archive lord@regexps.com--2002 \
            ftp://ftp.regexps.com/{archives}/lord@regexps.com--2002

You can see that these commands have taken effect:

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

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:


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

        % larch 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:

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

There are two other ways to access a remote archive:

Selecting an Archive with -A

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

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

        % larch categories -A lord@emf.net--2003
        [... categories in lord@emf.net--2003 ...]


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

Fully Qualified Project Names

Commands that accept project names allow you to use 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:
   arch                     => lord@emf.net--2003/arch

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

   version name:
   arch--devo--1.0          => lord@emf.net--2003/arch--devo--1.0

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


As in this example:

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

        % larch branches lord@emf.net--2003/arch
        [... branches of arch in lord@emf.net--2003 ...]


Usage Note: A fully qualified name takes precedence over both -A arguments and your default archive.

Read-only Archives

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.

Read-only Archive Mirrors

Upcoming Change Warning: The mechanism described in this section is going to change in future releases. Mirrors will be more cleanly supported. Nevertheless, this mechanism is currently widely adopted since it works well enough to get work done.

One popular way to use arch is to use a local (i.e. not network accessible) archive for day-to-day work, but then to "publish" that archive on the network by creating an archive mirror .

A mirror is created by:

1) Creating an initially empty network-accessible archive.

2) Storing a file called =mirror in the =meta-data directory in the root of the remote archive. That file should contain one line: the name of the archive being mirrored.

3) Using the command larch push-mirror to copy data from the local archive to the mirror:

    % larch push-mirror lord@emf.net--2003 lord@emf.net--2003-mirror
    [....]

Usage Note: Users do not generally run push-mirror by hand. Instead, they create something called a notifier that optimizes push-mirror by keeping track of what parts of the archive have previously been copied. You'll learn more about notifiers in a later chapter (see xref Driving Process Automation with arch Notifiers ).

Usage Note: When you tell other people about your network accessible mirror, tell them to register it under the name of your local archive. As far as remote users are concerned, the mirror is the same thing as your local archive.

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 ftp: URL.

Creating FTP Archives

An archive is made FTP accessible simply by putting its directory in a location where an FTP server can make it available.

Security Cautions: When creating an FTP accessible archive, there are two important security concerns: passwords in the clear, and FTP server configuration.

Passwords in the Clear As is well known, the FTP protocol sends passwords across networks unencrypted. In many situations, that is considered an unacceptable security risk and you will therefore want to consider using FTP access only for public data, and then only for read-only access.

FTP Server Configuration In general, securely configuring an FTP server requires care, caution, and careful study of the relevant documentation for the operating system and server implementation you will be using.

Creating SFTP Archives

[This isn't documented yet.]

Creating WebDAV and HTTP Archives

[This isn't documented yet.]

arch Meets hello-world: A Tutorial Introduction to The arch Revision Control System
The Hackerlab at regexps.com