Importing the First Revision

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 Ids for Source you assigned inventory ids 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

        % tla 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

or you could simply:

    % vi `tla make-log`

Storing the First Revision in the Archive

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

        % tla import
        [....]

Note: If you have received an error along the lines of These apparent source files lack inventory ids , please reread Inventory Ids for Source and either add each file or change the id-tagging-method to names.

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:

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

In fact, we can get more detail:

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

        % tla log-versions
        lord@emf.net--2003-example/hello-world--mainline--0.1

Now it has an entry:

        % tla logs hello-world--mainline--0.1
        base-0

        % tla logs --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

        % tla 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
        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

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