@need 3200

@node Inventory Tags for Source
@chapter Inventory Tags for Source

@strong{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.

@need 3200

@section Two Names for Every File

In the @code{arch} world, every source file (and directory) in your project
tree has two names: a @geindex file path
@dfn{file path} and a @geindex inventory tag
@dfn{inventory tag}.


The @emph{@strong{file path}} of a file always begins with the string @code{./} and
continues with a relative path name.  It describes @emph{where} within a
source tree a file is located.


The @emph{@strong{inventory tag}} of a file is a (mostly) arbitrary string that is
unique to the file within the tree.


Ordinarily, when a file is moved, it's file path changes, but its
inventory tag remains the same.


For example, let's suppose that we have a tree with the files:

@example
@group

@end group
@group
        file path               inventory tag
        ---------               -------------
@end group
@group

@end group
@group
        ./hw.c                  i_tag_hw
        ./main.c                i_tag_main
@end group
@group

@end group
@end example

@noindent
but then we rename @code{hw.c} to @code{hello.c}.   Afterwards, we'll have:

@example
@group
        file path               inventory tag
        ---------               -------------
@end group
@group

@end group
@group
        ./hello.c               i_tag_hw
        ./main.c                i_tag_main
@end group
@group

@end group
@end example

This chapter will teach you how tags are assigned to files, how
tags are managed, and how they are used by @code{arch}.




@need 3200

@section Why is it Like This -- The Purpose of Inventory Tags

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


As an example, let's suppose that Alice and Bob are both working on
the @code{hello_world} project.  In her tree, Alice makes some changes to
@code{hw.c}.  In his tree, Bob renames @code{hw.c} to @code{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.


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


Alice can ask @code{arch} to create a changeset describing the work she's
done, and that changeset will describe the changes she made within
@code{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 @code{hw.c}
should be renamed @code{hello.c}.   But a trickier case is this:  What
happens if Bob applies Alice's changeset to his tree?


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

@example
@group

@end group
@group
        file path               inventory tag
        ---------               -------------
@end group
@group

@end group
@group
                 Alice's tree:
        ./hw.c                  i_tag_hw
@end group
@group

@end group
@group
                 Bob's tree:
        ./hello.c               i_tag_hw
@end group
@group

@end group
@end example

In Alice's changeset, the changes Alice made are described as being
made to the file whose tag is @code{i_tag_hw}.


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


That example illustrates what inventory tags are for: they allow
@code{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 tags come into play, but
now you've seen at least the basic point.




@need 3200

@section Choices about Tags -- Introducing tagging-method

So, how are files given inventory tags?  Filesystems do not, as a
general rule, have any such concept as inventory tags built-in.
Operating systems don't have inventory tags built-in.  Rather, users
have to take explicit action to assign tags to files and to maintain
that assignment.


@code{arch} gives you a choice.  There are three possible ways you can
assign tags to files.   When you first create a project, you choose
from one of these three techniques.


The possibilities are briefly introduced here, then in more detail
below.


@strong{The names Method of Tagging} You @emph{are} free to just ignore tags -- to
not use them at all.  This is called the @code{names} method of tagging.
In this method, the inventory tag of every file is essentially the
same as the file path of that file.  As a result, if you rename a
file, its tag changes:

@example
@group

@end group
@group
           The names Method of Tagging
@end group
@group


@end group
@group
        file path               inventory tag
        ---------               -------------
@end group
@group

@end group
@group
                Before a rename
        ./hw.c                  ?./hw.c
@end group
@group

@end group
@group
                 After a rename
@end group
@group

@end group
@group
        ./hello.c               ?./hello.c
@end group
@group

@end group
@end example

If you don't care about synchronizing changes between trees in which
files have been renamed, the @code{names} method is the easiest to use.


@strong{The explicit Method of Tagging} In the @code{explicit} method, inventory
tags are stored @emph{separately} from files, in subdirectories called
@code{.arch-ids}.  Using this method most resembles using older revision
control systems such as @code{CVS}: if you add a new source file, you must
use the command @code{larch add} to assign it a tag; if you remove a file,
you must use @code{larch delete} to remove its tag; if you rename a file,
you must use @code{larch move} to move the corresponding tag file.  This is
a tried-and-true technique, but some users find the necessity of
issuing commands like @code{add}, @code{delete}, and @code{move} to be inconvenient.


@strong{The implicit Method of Tagging} The @code{implicit} method is a superset
of both the @code{explicit} method and the @code{names} method.  You @emph{may}, for
a particular file, define no tag -- in which case it works like the
@code{names} method.  You @emph{may} define a tag using @code{larch add} -- in which
case it works like the @code{explicit} method.  However, the real
@emph{convenience} of the @code{implicit} method comes from this: you @emph{may}
define the tag for a file by adding a specially formatted string near
the top or bottom of that file (e.g., in a comment for source files).


I strongly recommend the @code{implicit} method, even though it is the
least familiar to new users.   As you'll see below, its convenience
far outweighs its drawbacks.




@need 3200

@section Setting the Tagging Method

To set or check the tagging method for a tree, use the
@code{tagging-method} command:

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

@end group
@group
        # set the tagging method
        # 
        % larch tagging-method implicit
@end group
@group


@end group
@group
        # check the tagging method
        # 
        % larch tagging-method
        implicit
@end group
@group

@end group
@end example

Possible values when setting a tagging method are @code{names}, @code{explicit},
and @code{implicit}.




@need 3200

@section Using the names Tagging Method 

@geindex names tags



If you want to use the @code{names} method of tagging, use this command:

@example
@group
        % larch tagging-method names
@end group
@group
@end group
@end example

Thereafter, every file will have a tag that is derived from its path
relative to the tree root.


(Again, the @code{names} tagging method has the disadvantage that
changesets do not work cleanly if files have been renamed.)




@need 3200

@section Using the explicit Tagging Method

@geindex explicit tags

@geindex add

@geindex delete

@geindex move



If you want to use the @code{explicit} method of tagging, use this command:

@example
@group
        % larch tagging-method explicit
@end group
@group
@end group
@end example

When using the @code{explicit} method, it is (ordinarily) necessary to 
use @code{larch add} to tag every file and directory:

@example
@group
        % larch add FILE
@end group
@group
@end group
@end example

If @code{FILE} is a directory, that will create @code{FILE/.arch_ids/=id}.  If
it is a regular file or symbolic link, it will create (in the same
directory) @code{.arch_ids/FILE.id}.  In either case, the file created will
contain an automatically generated tag for the file.


If you remove a regular file or symbolic link, you must use the
command:

@example
@group
        % larch delete FILE
@end group
@group
@end group
@end example

That won't remove @code{FILE} itself, but it will remove the inventory tag
for @code{FILE}.


In order to remove a directory, you must yourself remove the
@code{.arch_ids} subdirectory.  That will also implicitly remove the
inventory tags of any files that @code{arch} thinks are stored in that
directory.  (For example, using @code{rm -rf} to remove a directory also
removes its tag.)


If you rename a regular file or symbolic link, you can use the
command:

@example
@group
        % larch move OLD-NAME NEW-NAME
@end group
@group
@end group
@end example

@noindent
to move the inventory tag for that file.


@strong{Usage Note:} @code{larch move} does not work like the unix command @code{mv}.
In particular, @code{NEW-NAME} must be the new name of the file -- not the
name of a directory into which the file is being moved.


If you rename a directory, its inventory tag (and the tags for all
files and subdirectories it contains) move with it automatically
(because the @code{.arch_ids} subdirectory has moved).


When you run @code{larch inventory} in a working directory using explicit
tagging, only explicitly designated source files are listed. 
If you would rather see a list of all files passing the naming
conventions for source files, use:

@example
@group
        % larch inventory --source --names
@end group
@group
@end group
@end example

You should also read about @code{tree-lint} (see @strong{Keeping Things Neat and Tidy} in @ref{Inventory Tags for Source}).




@need 3200

@section Using an Implicit Inventory

@geindex implicit tags



To use implicit tagging, use the following command in your project
tree:

@example
@group
        % larch tagging-method implicit
@end group
@group
@end group
@end example

With this method: any file with @emph{no} tag is assigned a tag based on
its location -- just as in the @code{names} method.  Any file assigned a
tag with @code{larch add} uses that tag -- just as in the @code{explicit}
method.  Finally, though, you can tag a file by adding a specially
formatted string near the top or bottom of the file.


A tag within a file is a single line that occurs within @code{1024} bytes of
the start or end of the file and has the form:

@example
@group
        <punct>tag:<spaces><tag>
@end group
@group
@end group
@end example

For example:

@example
@group

@end group
@group
        /* tag: `main' for the hello world program
         */
@end group
@group

@end group
@end example

@strong{Note:} Leading and trailing spaces around an inventory tag are not
considered part of the tag.  Within a tag, every non-graphical
character is replaced by @code{_}.  For example, you write the that tag:

@example
@group
        `main' for the hello    world program
@end group
@group
@end group
@end example

@noindent
the actual inventory tag is:

@example
@group
        `main'_for_the_hello____world_program
@end group
@group
@end group
@end example



@need 3200

@section Keeping Things Neat and Tidy

@geindex tree-lint



The command:

@example
@group
        % larch tree-lint
@end group
@group
@end group
@end example

@noindent
is useful for keeping things neat and tidy.


If you use @code{explicit} tagging, it will tell you of any tags 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 tag
exists.


If you use @code{implicit} tagging, it will tell you of any files for which
no tag can be found -- either explicit or implicit.  It will tell you
of any explicit tags for which the corresponding file does not exist.


In either case, or if you are using the @code{names} tagging method,
@code{tree-lint} will tell you of any files that don't fit the naming
conventions at all.


Finally, if you use explicit or implicit tagging, @code{tree-lint} will
check for cases where multiple files use the same tag.  If any two
files do have the same tag, you @emph{@strong{must}} correct that, either by
editing the tag (if it is in the file itself) or by using @code{delete}
and @code{add} to replace a duplicated explicit tag.




@need 3200

@section Tagging the hello-world Project

To continue the example started in earlier chapters: let's use the
@code{implicit} tagging method for the @code{hello-world} project:

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

@end group
@group
        % larch tagging-method implicit
@end group
@group
@end group
@end example

So, what does @code{tree-lint} tell us?

@example
@group
        % larch tree-lint
        [...]
        ** WARNING: untagged files
@end group
@group
        
@end group
@group
           This directory uses the "implicit" inventory method, but
           these files do not have either implicit or explicit tags.
@end group
@group
        
@end group
@group
        *** file-list
@end group
@group
        
@end group
@group
                ./hw.c
                ./main.c
@end group
@group
@end group
@end example

If we edit the source files to add tags:

@example
@group
        % tail -3 main.c
@end group
@group
        
@end group
@group
        /* tag: main module of the hello-world project
         */
        % tail -3 hw.c
@end group
@group
        
@end group
@group
        /* tag: hello_world module of the hello-world project
         */
@end group
@group
@end group
@end example

Then the next run of @code{tree-lint} omits the warning.


@strong{Usage Note 1:} Notice that we didn't tag any of the files in @code{@{arch@}}.
@code{arch} implicitly provides tags for all of its control files.


@strong{Usage Note 2:} Our little sample project doesn't have any
subdirectories other than @code{arch} control directories.  If it did, we
might want to tag those with @code{larch add}.




@need 3200

@section Other Ways to Tag Files

@geindex explicit-default



In some situations, it isn't convenient to explicitly tag every file
or to add an implicit tag to every file.


You can supply a @geindex default tag
@dfn{default tag} for every file in a directory that
doesn't have an explicit tag with the command:

@example
@group
        % larch explicit-default TAG-PREFIX
@end group
@group
@end group
@end example

After that, every file in that directory which lacks an explicit tag
will have the tag:

@example
@group
        TAG-PREFIX__BASENAME
@end group
@group
@end group
@end example

@noindent
where @code{BASENAME} is the basename of the file.  Default tags created in
this way take precedence over implicit tags embedded in files.  You
can find out the default tag for a directory with:

@example
@group
        % larch explicit-default
        TAG-PREFIX
@end group
@group
@end group
@end example

@noindent
and remove the default with:

@example
@group
        % larch explicit-default --delete
@end group
@group
@end group
@end example

You can also specify a default tag which has @emph{lower} precedence than
implicit tags:

@example
@group
        % larch explicit-default --weak TAG-PREFIX
@end group
@group
@end group
@end example

@noindent
and view that default:

@example
@group
        % larch explicit-default --weak
@end group
@group
@end group
@end example

@noindent
or delete it:

@example
@group
        % larch explicit-default --weak --delete
@end group
@group
@end group
@end example



@need 3200

@section Telling tree-lint to Shut Up

@geindex dont-care

@geindex explicit-default



When using implicit tags, you may sometimes have a directory with many
files that have no tag (either explicit or implicit), but not want
those files to appear in a report of untagged files generated by
@code{tree-lint}.  There are two ways to tell @code{tree-lint} to shut-up
about such files:


One is to provide a default explicit tag or weak default explicit tag
using @code{larch explicit-default}, as described above.  


The second method is to label the directory as a "don't care"
directory -- which means that @code{tree-lint} shouldn't complain about
untagged files.  You can do that with:

@example
@group
        % larch explicit-default --dont-care set
@end group
@group
@end group
@end example

@noindent
or remove the "don't care" flag with:

@example
@group
        % larch explicit-default --delete --dont-care
@end group
@group
@end group
@end example

You can find out whether the "don't care" flag is set in a given
directory with:

@example
@group
        % larch explicit-default --dont-care
@end group
@group
@end group
@end example






