regexps.com
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.
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`
Shortcut Note: This section describes the "long way" to make the
log entry to go with your initial import.  There is a short-cut that
can let you skip this step: the -L
 and -s
 options to tla import
.
We've walked though the long way here but later you might want to try
tla import -H
 to learn about the shortcut'.
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.
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.
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).
regexps.com