Previous: Inventory Ids for Source, Up: Getting Started
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 apparent source files lack inventory ids 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 qualified revision name 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).