@need 3200

@node Importing the First Revision
@chapter Importing the First Revision

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


@strong{Your arch User ID} In @ref{Introducing Yourself to arch}, you set an
ID string that @code{arch} uses to identify you.


@strong{Your First Archive}  In @ref{Creating a New Archive}, you created 
your first archive and made that your default archive.  In
@ref{Starting a New Project} you added the @code{hello-world} project to
that archive.


@strong{Your Initial Source Tree} In @ref{Starting a New Source Tree} you
began to initialize the sources for @code{hello-world} as an @code{arch} project
tree and in @ref{Inventory Ids for Source} you assigned inventory
ids to the source files in that project.


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

@need 3200

@section Making the First Log File

@geindex make-log-file



You're about to create a new @geindex revision
@dfn{revision} of @code{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:

@example
@group

@end group
@group
        % cd ~/wd/hello-world
@end group
@group

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

@end group
@end example

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

@example
@group
        Summary: 
        Keywords: 
@end group
@group
@end group
@end example

You should fill out this file just like an email message.  Add a short
description of the revision in the @code{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:

@example
@group
        Summary: initial import
        Keywords: 
@end group
@group

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

@end group
@end example

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

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

@noindent
or you could simply:

@example
@group
    % vi `tla make-log`
@end group
@group
@end group
@end example

@strong{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 @code{-L} and @code{-s} options to @code{tla import}.
We've walked though the long way here but later you might want to try
@code{tla import -H} to learn about the shortcut'.




@need 3200

@section Storing the First Revision in the Archive

@geindex import

@geindex revisions



Finally, we can ask @code{arch} to add our source to the archive:

@example
@group
        % tla import
        [....]
@end group
@group
@end group
@end example

@strong{Note:} If you have received an error along the lines of @geindex These
apparent source files lack inventory ids
@dfn{These
apparent source files lack inventory ids}, please reread 
@ref{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 @code{arch} what revisions exist in the archive 
for our project:

@example
@group
        % tla revisions hello-world--mainline--0.1
        base-0
@end group
@group
@end group
@end example

In fact, we can get more detail:

@example
@group
        % 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
@end group
@group
@end group
@end example

What's changed in the project tree?   Recall that we have something
called a @geindex patch log
@dfn{patch log}:

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

Now it has an entry:

@example
@group
        % tla logs hello-world--mainline--0.1
        base-0
@end group
@group

@end group
@group
        % 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
@end group
@group

@end group
@group
        % 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
@end group
@group
        Standard-date: 2003-01-28 00:45:50 GMT
@end group
@group
        Summary: initial import
        Keywords: 
        New-files: ./hw.c ./main.c
        New-patches: \
          lord@@emf.net--2003-example/hello-world--mainline--0.1--base-0
@end group
@group

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



@need 3200

@section Revision Names from import

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

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

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

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

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




@need 3200

@section How it Works -- What import Does

Let's look at what @code{import} did to the archive:

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

It created a new @code{base-0} directory for the revision.

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

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


The @code{log} file is a copy of the log message you wrote, with some
additional headers added:

@example
@group
        % 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
@end group
@group
        Standard-date: 2003-01-28 00:45:50 GMT
@end group
@group
        Summary: initial import
        Keywords: 
        New-files: ./hw.c ./main.c
        New-patches: \
          lord@@emf.net--2003-example/hello-world--mainline--0.1--base-0
@end group
@group

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

@end group
@end example

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

@example
@group
        % 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/
        [....]
@end group
@group
@end group
@end example

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

@example
@group
        % cd ~/wd/hello-world
@end group
@group

@end group
@group
        % tla inventory --source --both --all
        [....]
@end group
@group
@end group
@end example

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

@example
@group
        % ls
        ++default-version       =tagging-method
        ++pristine-trees        hello-world
@end group
@group
@end group
@end example

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


If you dig around in the @code{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).







