The Hackerlab at `regexps.com`

## Importing the First Revision

up: arch Meets hello-world next: Checking-in Changes prev: Inventory Tags for Source

Just to Review: If you've been following the examples in the earlier chapters, we now have:

Your arch User ID In Introducing Yourself to arch, you set an ID string that `arch` uses to identify you.

Your First Archive In Creating a New Archive, you created your first archive and made that your default archive. In Starting a New Project you added the `hello-world` project to that archive.

Your Initial Source Tree In Starting a New Source Tree you began to initialize the sources for `hello-world` as an `arch` project tree and in Inventory Tags for Source you assigned inventory tags to the source files in that project.

Now it's finally time to import the sources for `hello-world` into your archive. That will happen in two steps: `(1)` create a log message; `(2)` import the sources.

### Making the First Log File

You're about to create a new revision of `hello-world` in your archive: a record of how that project looked at a particular point in time.

Whenever you create a new revision, the first step is to create a log file for that revision:

            % cd ~/wd/hello-world

            % larch make-log
            ++log.hello-world--mainline--0.1--lord@emf.net--2003-example

The output from that command is the name of a file which you must now edit. Initially it contains:

            Summary:
            Keywords:

You should fill out this file just like an email message. Add a short description of the revision in the `Summary:` field, and a full description in the body. Just as in email, the body must be separated from the headers by a blank line. When you're done, the log might look like this:

            Summary: initial import
            Keywords:

            This is the initial import of `hello-world', the killer app
            that will propel our new .com company to a successful IPO.

Usage Note for vi Fans: The default filename of log messages starts with the character `+` . `vi` is a non-standard program in the sense that it treats arguments starting with `+` as options rather than ordinary arguments. Therefore, you should be sure to type the filename for `vi` starting with `./` , as in:

        % vi ./++log.hello-world--mainline--0.1--lord@emf.net--2003-example

(We expect, in the future, to change the default name of log files so that you will no longer need a `./` prefix.)

### Storing the First Revision in the Archive

Finally, we can ask `arch` to add our source to the archive:

            % larch import
            [....]

We can observe the side effects of that command in a few ways.

For one thing, we can ask `arch` what revisions exist in the archive for our project:

            % larch revisions hello-world--mainline--0.1
            base-0

In fact, we can get more detail:

            % larch revisions --summary --creator --date \
                              hello-world--mainline--0.1
            base-0
                2003-01-28 00:45:50 GMT
                Tom (testing) Lord <lord@emf.net>
                initial import

What's changed in the project tree? Recall that we have something called a patch log :

            % larch logs
            lord@emf.net--2003-example/hello-world--mainline--0.1

Now it has an entry:

            % larch log-ls hello-world--mainline--0.1
            base-0

            % larch log-ls --summary --creator --date \
                           hello-world--mainline--0.1
            base-0
                2003-01-28 00:45:50 GMT
                Tom (testing) Lord <lord@emf.net>
                initial import

            % larch cat-log hello-world--mainline--0.1--base-0
            Revision: hello-world--mainline--0.1--base-0
            Archive: lord@emf.net--2003-example
            Creator: Tom (testing) Lord <lord@emf.net>
            Date: Mon Jan 27 16:45:50 PST 2003
            Standard-date: 2003-01-28 00:45:50 GMT
            Summary: initial import
            Keywords:
            New-files: ./hw.c ./main.c
            New-patches: \
              lord@emf.net--2003-example/hello-world--mainline--0.1--base-0

            This is the initial import of `hello-world', the killer app
            that will propel our new .com company to a successful IPO.

### Revision Names from import

`import` created a new revision in the archive. Note that the revision it created is called `base-0` and that we can form a longer name for that revision by prepending the category, branch, and version:

            hello-world--mainline--0.1--base-0
            ^^^^^^^^^^^  ^^^^^^^^  ^^^  ^^^^^^
                 |          |       |     |
                 |          |       |    patch level name
                 |          |       |
                 |          |     version number
                 |          |
                 |     branch name
                 |
             category name

If we add in the archive name, we get something called a fully qualified revision name , which is a globally unique identifier for the revision:

        lord@emf.net--2003-example/hello-world--mainline--0.1--base-0
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
                    |
              archive name

Fully qualified names will be of increasing importance as you learn about distributed repositories in later chapters.

### How it Works -- What import Does

Let's look at what `import` did to the archive:

            # cd to the directory for the version we are working
            # on:
            #
            % cd ~/{archives}
            % cd 2003-example/
            % cd hello-world/
            % cd hello-world--mainline/
            % cd hello-world--mainline--0.1/
            % ls
            % ls
            +version-lock   =README         base-0

It created a new `base-0` directory for the revision.

            % cd base-0
            % ls
            +revision-lock
            hello-world--mainline--0.1--base-0.src.tar.gz
            log

As always, the `+revision-lock` file is something `arch` uses internally to keep the archive in a consistent state under all circumstances.

The `log` file is a copy of the log message you wrote, with some additional headers added:

            % cat log
            Revision: hello-world--mainline--0.1--base-0
            Archive: lord@emf.net--2003-example
            Creator: Tom (testing) Lord <lord@emf.net>
            Date: Mon Jan 27 16:45:50 PST 2003
            Standard-date: 2003-01-28 00:45:50 GMT
            Summary: initial import
            Keywords:
            New-files: ./hw.c ./main.c
            New-patches: \
              lord@emf.net--2003-example/hello-world--mainline--0.1--base-0

            This is the initial import of `hello-world', the killer app
            that will propel our new .com company to a successful IPO.

Finally, the compressed tar file is a copy of the source files in your project tree:

            % tar ztf hello-world--mainline--0.1--base-0.src.tar.gz
            hello-world--mainline--0.1--base-0/
            hello-world--mainline--0.1--base-0/hw.c
            hello-world--mainline--0.1--base-0/main.c
            hello-world--mainline--0.1--base-0/{arch}/
            hello-world--mainline--0.1--base-0/{arch}/.arch-project-tree
            hello-world--mainline--0.1--base-0/{arch}/=tagging-method
            hello-world--mainline--0.1--base-0/{arch}/hello-world/
            [....]

You should notice that the tar file does not include every file from your project tree. Specifically, it contains those files that are listed by:

            % cd ~/wd/hello-world

            % larch inventory --source --both --all
            [....]

Finally, if you poke around in the `{arch}` subdirectory of your project tree, you'll see two new items:

            % ls
            ++default-version       =tagging-method
            ++pristine-trees        hello-world

The directory `++pristine-trees` contains (at some depth) a copy of the tree you just imported. This is a cached copy used by other `arch` commands. (Note: In future releases of `arch` , it is likely that the `++pristine-trees` subdirectory will be replaced by a different mechanism.)

If you dig around in the `hello-world` (patch log) directory, you can find a local copy of the log file for the revision you just created (with extra headers added to that log file).

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