3.3 Creating a New Archive

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

3.3.1 Choose a Location

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

Usage Advice: It is likely that you'll eventually want to have 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 ~/archives, a directory of archives.

             # Create a directory in which to store archives:
             #
             % mkdir ~/archives

3.3.2 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 (--), followed by a suffix. By convention, the email address should be that of the archive owner.

In the example, we'll use the name:

             lord@emf.net--2003-example

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 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 time and that suggests that you include a date in the archive name. In the example above, the archive is labeled 2003: a year later, we could create lord@emf.net--2004-example and continue the project in that new archive. The 2003 archive will still exist at that point – we'll just stop adding new data to it.

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

3.3.3 Create the Archive

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

             # Create the new archive
             #
             % tla make-archive lord@emf.net--2003-example \
                                  ~/archives/2003-example

3.3.4 Make this Your 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:

             # Choose a default archive
             #
             % tla my-default-archive lord@emf.net--2003-example

Your current default is reported by:

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

And you can cancel the default setting with:

             % tla my-default-archive -d
             user default archive removed

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

3.3.5 How it Works – New Archives

Let's examine what that command did.

First, tla now knows about the new archive:

             # What archives does `tla' know about?
             #
             % tla archives
             lord@emf.net--2003-example
                     /home/lord/archives/2003-example

             % tla whereis-archive lord@emf.net--2003-example
             /home/lord/archives/2003-example

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

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

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

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

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

             % ls ~/archives
             2003-example

             % ls -a ~/archives/2003-example
             .                       .archive-version
             ..                      =meta-info

             % cat ~/archives/2003-example/.archive-version
             Hackerlab arch archive directory, format version 2.

             % ls -a ~/archives/2003-example/=meta-info/
             .       ..      name

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

Caution: You usually should not edit files in ~/.arch-params/ or files in an archive "by hand."