Inventory Ids for Source

Caution: Steep Learning Curve: As in the previous chapter, the
concepts and commands introduced here are likely to be unfamiliar to
you, even if you have used other revision control systems. Once
you "get it", though, this will seem quite natural. Best of all,
this is the last tricky step before we can start storing project trees
in an archive.

Looks Like Source vs Really is Source

In the previous chapter, we saw how to find out which files look like
source according to the naming conventions:

% tla inventory --names --source
hw.c
main.c

In this chapter, there's a new distincition: files which look like
source according to their names, vs. files which really are source.

When you save your project tree in an archive, arch will store the
files that really are source and ignore the rest. We can ask which
files really are source by dropping the --names
option to
inventory
:

% tla inventory --source
[no output]

It's a little more interesting if we include arch's own "system
files and directories" in the listing:

but the thing to note here is that hw.c
and main.c
aren't listed.
Arch thinks they are source in name only. The next section gives a
recipe to fix that, and the sections after that explain what's really
going on.

The add Command

We can tell arch that our files really are source, and should really
be archived with the project, using the tla add
command:

% tla add hw.c
% tla add main.c

And now we get a better answer from:

% tla inventory --source
hw.c
main.c

A related command is tla delete
:

% tla delete hw.c

That doesn't delete the file hw.c
itself:

% ls
hw.c hw.c.~1~ main.c {arch}

but it does remove it from the official list of source:

% tla inventory --source
main.c

For the sake of the examples, we need to put hw.c
back in the list:

% tla add hw.c

% tla inventory --source
hw.c
main.c

Let's take a deeper look at what's going on when you tla add
files:

Two Names for Every File

In the arch
world, every source file (and directory) in your project
tree has two names: a
file path
and a
inventory id
.

The file path of a file is the relative path to the file from the
root of the project tree. It describes where within a source tree a
file is located.

The inventory id of a file is a (mostly) arbitrary string that is
unique to the file within the tree. The inventory id remains
constant even if a file is renamed. So while the file path says
where a file is located, the inventory id says which file it is
that's stored at that path.

We'll come back to the topic of renames later so, for now, let's
put things back where they started:

% mv hello.c hw.c
% tla move hello.c hw.c

Quick Aside -- Adding Directories

The tla add
command applies to directories, too. If we were to
create a new subdirectory in the tree, we should tla add
it:

% mkdir docs

% tla inventory --names --source --both
docs
hw.c
hello.c

but

% tla inventory --source --both
hw.c
hello.c

unless

% tla add docs

and then

% tla inventory --source --both
docs
hw.c
hello.c

But again, for the sake of our example, we don't need docs.
We can just:

% rm -rf docs

There isn't a need to tla delete
a directory that we physically remove.

How it Works -- tla add

What tla add
does is fairly simple. Note that when we added
hw.c
and main.c
, a new directory was created:

% ls -a
. .arch-ids hw.c.~1~ {arch}
.. hw.c main.c

The .arch-ids
directory is new:

% ls .arch-ids
hw.c.id main.c.id

% cat .arch-ids/hw.c.id
very long string

The *.id
files is where the raw data that determines a file id are
stored. The command tla delete
removes those files. The command
tla move
renames them.

The id for a directory is stored slightly differently. For example,
when we created a docs
subdir and gave it an id with tla add
, that
created a file docs/.arch-ids/=id
.

Keeping Things Neat and Tidy

The command:

% tla tree-lint

is useful for keeping things neat and tidy.

tree-lint
will tell you of any ids for which the corresponding file
does not exist. It will tell you of any files that pass the naming
conventions, but for which no explicit id exists.

It will also warn you about files that don't fit the naming
conventions.

Inventory Ids -- There's More Than One Way to Do It

In this chapter, you've learned about the basic commands add
,
move
, and delete
.

The use of those tools for managing inventory ids was chosen as the
default behavior because, superficially at least, it resembles similar
commands in systems such as CVS which many users are already familiar
with.

There are other ways to manage inventory ids. Sometimes the other
ways are more convenient. A later chapter discusses these other
techniques (see: xref :
!!!
).

Why is it Like This -- The Purpose of Inventory Ids

As you'll see in later chapters, arch
is good at managing changes
made to source trees and the files they contain, and good at telling
you about the history of trees and files.

As an example, let's suppose that Alice and Bob are both working on
the hello_world
project. In her tree, Alice makes some changes to
hw.c
. In his tree, Bob renames hw.c
to hello.c
.

At some point it is necessary to "sync-up" Alice and Bob. Bob
should wind up with the changes Alice has been making. Alice should
wind up with the same file renaming that Bob has done.

arch
provides many mechanisms for that syncing up -- it's one of the
most important things that arch
can do -- but nearly all of them
boil down to computing and applying changesets.

Alice can ask arch
to create a changeset describing the work she's
done, and that changeset will describe the changes she made within
hw.c
. Bob can create a changeset and that changeset will describe
the file renaming he did.

If Alice applies Bob's changeset to her tree, her copy of hw.c
should be renamed hello.c
. But a trickier case is this: What
happens if Bob applies Alice's changeset to his tree?

Alice changed a file named ./hw.c
, but in Bob's tree, those same
changes should be made to a file named ./hello.c
. Fortunately, both
files have the same inventory id:

In Alice's changeset, the changes Alice made are described as being
made to the file whose id is x_very_long_string
.

Therefore, when applying that changeset to Bob's tree, arch
knows to
apply the changes to the file with that same id; it knows to apply
the changes to his ./hello.c
.

That example illustrates what inventory ids are for: they allow
arch
to describe the changes made to a tree in terms of the logical
identity of files rather than their physical location. There are many
more complicated examples of how inventory ids come into play, but
now you've seen at least the basic point.

Why is it Like This -- Why tla move Doesn't Move Files

Those commands work as they do so that you can adjust the ids in a
tree even if some other tool which knows nothing about arch has
rearranged files. For example, if you use a "directory editor" to
rename source files, tla move
is available to catch-up to the
changes the directory editor made.

Sometimes, arch users request the addition of commands: tla mv
, tla
mkdir
, tla rmdir
, and tla rm
that would modify both ids and
the corresponding source files. That's a great idea and it's not all
that hard: so, if you're looking for something to do, that's a good
idea for a real-world programming project on which to try-out and
learn arch. Let us know on the gnu-arch-users
mailing list if you
do this, so that we can consider merging your changes into the
distribution.