The Hackerlab at `regexps.com`

## Creating a New Archive

up: arch Meets hello-world next: Starting a New Project prev: Introducing Yourself to arch

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.

### 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}

### 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.

### 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
            #
            % larch make-archive lord@emf.net--2003-example \
                                 ~/{archives}/2003-example

### 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
            #
            % larch my-default-archive lord@emf.net--2003-example
            default archive set (lord@emf.net--2003-example)

Your current default is reported by:

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

And you can cancel the default setting with:

            % larch 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.)

### How it Works -- New Archives

Let's examine what that command did.

First, `larch` now knows about the new archive:

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

            % larch 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 1.

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

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

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

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