@need 3200

@node Project Tree Inventories
@chapter Project Tree Inventories

@strong{Caution: Steep Learning Curve:}  The concepts and commands introduced
in this chapter are likely to be unfamiliar to you, even if you have 
used other revision control systems.   They're really quite simple
once you get over the initial learning hurdle -- and after that
they're very useful.

@need 3200

@section The Name-based inventory Concept

In a project tree, some of the files and directories are "part of
the source" -- they are of interest to @code{arch}.  Other files and
directories may be scratch files, editor back-up files, and temporary
or intermediate files generated by programs.  Those other files should
be ignored or treated specially by most @code{arch} commands.


This chapter discusses how @code{arch} recognizes which files to pay
attention to, and which to ignore.

@menu
@end menu




@need 3200

@section The inventory Command

@geindex inventory



The command @code{tla inventory --names --source} is used to print a list
of source files as determined by the naming conventions.  It has many
options, including options to print other kinds of file lists (such as
a list of all editor backup files, or a list of all files which are
not source).


Let's suppose that after some editing, our source tree looks like
this:

@example
@group
        % ls
        hw.c            hw.c.~1~        main.c          @{arch@}
@end group
@group
@end group
@end example

The file @code{hw.c.~1~} is an editor backup file. @code{tla} knows that
and omits that file from the source inventory:

@example
@group
        % tla inventory --names --source
        ./hw.c
        ./main.c
@end group
@group
@end group
@end example

@code{tla} can give you other lists besides lists of source:

@example
@group
        % tla inventory --names --backups
        ./hw.c.~1~
@end group
@group
@end group
@end example



@need 3200

@section The arch Naming Conventions

@geindex naming conventions



This section describes the default naming conventions used by @code{arch}
to pick out source files from other kinds of files.  A later chapter
describes how to customize these conventions for a partiuclar tree
(see @ref{Customizing the inventory Naming Conventions}).


The naming conventions are based on several categories of files:

@example
@group

@end group
@group
        . and ..                These are simply ignored by arch
@end group
@group

@end group
@group
        excluded                Excluded files are normally omitted
                                from a listing, but if the `--all'
                                flag is passed to `inventory', 
                                then these files are put into 
                                one of the categories below and
                                included in the listing.
@end group
@group

@end group
@group
        source                  These are apparent source files
@end group
@group

@end group
@group
        precious                These are non-source files that 
                                should not be automatically deleted
@end group
@group

@end group
@group
        junk                    These are non-source files that
                                may be automatically deleted
@end group
@group

@end group
@group
        backups                 These are non-source files that
                                may be automatically deleted, but
                                any program that deletes them should
                                treat them as editor backup files
                                (e.g., keep the oldest and newest
                                of them)
@end group
@group

@end group
@group
        unrecognized            These are files that arch doesn't
                                know how to classify -- they fit
                                none of the naming conventions or
                                that have names that appear to
                                be "suspicious".
@end group
@group

@end group
@end example

The algorithm for classifying files by name has several rules.  For 
each file name, each of these rules is checked in the order listed
here until the first rule is reached that classifies the file.


@strong{Exclude Dot Files}  The special files @code{.} and @code{..} are always 
excluded from inventory listings.


@strong{Non-portable Names are Unrecognized}  File names containing
whitespace, non-printing characters, or a "globbing character" are
always classified as @code{unrecognized}.   The globbing characters 
are:

@example
@group
        ? [ ] * \
@end group
@group
@end group
@end example

@strong{Excluded File Test} If the @code{--all} flag is @emph{not} given to
@code{inventory}, the file names matching the pattern for excluded files
are dropped from the listing.  If the name of a directory is excluded,
the entire contents of that directory are skipped.  By default, the
pattern for excluded files matches control files created by @code{arch}
itself:

@example
@group
        ^(.arch-ids|\@{arch\@})$
@end group
@group
@end group
@end example

@strong{Junk File Test} All file names reaching this step that begin with two
commas (@code{,,}) are classified as @code{junk}.  Temporary files created by
@code{arch} itself begin with two commas.  In addition, any file name
matching the junk pattern are classified by @code{junk}.  By default, that
pattern matches any name beginning with (at least) one comma:

@example
@group
        ^,.*$
@end group
@group
@end group
@end example

Incidentally, that default pattern gives rise to a handy trick.  If you
need to create a scratch file in a source tree, give it a name that
begins with a single comma.


@strong{Backup File Test} By default, a backup file is any file that reaches this
step and matches one of the patterns:

@example
@group
        ^.*(~|\.~[0-9]+~)$
        ^.*\.bak|\.orig|\.rej|\.original|\.modified|\.reject)$
@end group
@group
@end group
@end example

@strong{Precious File Test} By default, a precious file is any that reaches this
step and matches one of the patterns:

@example
@group
     ^\+.*$
     ^(\.gdbinit|\.#ckpts-lock)$
     ^(=build\.*|=install\.*)$
     ^(CVS|CVS\.adm|RCS|RCSLOG|SCCS|TAGS)$
@end group
@group
@end group
@end example

@strong{Suspicious File Test (Unrecognized)} Some file names reaching this step
are explicitly treated as @code{unrecognized} on the presumption that they
should probably not be present in a source tree.  By default, names
ending with any of these extensions are treated as @code{unrecognized}:

@example
@group
        .o
        .a
        .so
        .core
@end group
@group
@end group
@end example

In addition, the filename @code{core} is (by default) treated as
@code{unrecognized}).


@strong{Source File Test} Files reaching this step are compared to the pattern
for source files.   The default pattern is shown below.  You should
note that this pattern overlaps that for @code{excluded} files given
above.  If the @code{--all} flag is given to inventory, the @code{excluded}
pattern isn't used, and files that would match it instead "fall
through" to later steps of this algorithm.

@example
@group
        ^([_=a-zA-Z0-9].*|\.arch-ids|\@{arch\@}|\.arch-project-tree)$
@end group
@group
@end group
@end example

In other words, by default, the @code{arch} control files and directories
are source (if not excluded).  Files beginning with letters, numbers, 
underscore, or an equal sign are source.


@strong{Unrecognized Files} Any left-over file name reaching this step is 
treated as @code{unrecognized}.




@need 3200

@section Naming Conventions Illustrated

Using our example, we can illustrate some of the naming conventions.


Recall that our project tree looks like this:

@example
@group
        % ls
        hw.c            hw.c.~1~        main.c          @{arch@}
@end group
@group
@end group
@end example

So the ordinary source listing is:

@example
@group
        % tla inventory --names --source
        ./hw.c
        ./main.c
@end group
@group
@end group
@end example

And all of the source files (none excluded from the list) is:

@example
@group
        % tla inventory --names --source --all
        ./hw.c
        ./main.c
        ./@{arch@}/.arch-project-tree
        ./@{arch@}/=tagging-method
@end group
@group
@end group
@end example

We can include directories in this listing:

@example
@group
        % tla inventory --names --source --all --both
        ./hw.c
        ./main.c
        ./@{arch@}
        ./@{arch@}/.arch-project-tree
        ./@{arch@}/=tagging-method
        ./@{arch@}/hello-world
        ./@{arch@}/hello-world/hello-world--mainline
        [... output trimmed ...]
@end group
@group
@end group
@end example

We can also look at some lists of non-source files:

@example
@group
        % tla inventory --names --backups
        ./hw.c.~1~
@end group
@group
@end group
@end example

The @code{inventory} command has many options that you may wish to explore.




@need 3200

@section Customizing the Naming Conventions

You can alter the patterns used by @code{inventory} to classify files.
This is explained in a later chapter (see @ref{Customizing the inventory Naming Conventions}).




@need 3200

@section Why is It Like This -- inventory Naming Conventions

Many systems provide naming conventions for recognizing source files
but users new to @code{arch} often wonder why @code{arch} needs so many
categories of files.   Recall that @code{arch} has the categories:

@example
@group
        excluded
        source
        precious
        junk
        backups
        unrecognized
@end group
@group
@end group
@end example

A rationale for each category is explained here:


@strong{excluded} is provided simply to keep inventory listings brief in the
very common case that @code{arch} control files are of no particular
interest.  This is similar to the treatment of "dot files" by @code{ls}
and the @code{--all} flag to @code{inventory} is similar to the @code{-a} flag to
@code{ls}.


@strong{source} is provides simply so that @code{arch} can reliably distinguish
those files from others.  For example, when comparing two source
trees, @code{arch} compares only the files in the category @code{source}.


@strong{precious} files are those that @code{arch} should make an effort to
preserve.  For example, if @code{arch} needs to make a copy of a project
tree for you, it copies the @code{precious} files along with the @code{source}.
Suppose, for example, that you are taking notes while working on
source.   You don't want your file of notes to be mistaken for source,
but you also don't want them to be lost.   A useful trick is to give the
file a @code{precious} name (e.g. @code{+notes}).


@strong{junk} Often when working on a project tree, it's convenient to create
"throw-away" files.   You might want to compile a quick test program
or save, for the moment, the output of some command.   When enough of
these throw-away files have accumulated, it's handy to be able to get
rid of them all-at-once, without having to carefully identify which
files to toss, and which to keep.   @code{junk} names are perfect for this.   
When you create one of these throw-away files, give it name like
@code{,foo}.   Later, you can feel confident and safe issuing commands
like:

@example
@group

@end group
@group
        % rm ,*
@end group
@group

@end group
@group
        % find . -name ',*' | xargs rm
@end group
@group

@end group
@group
        % tla inventory --junk | xargs rm
@end group
@group

@end group
@end example

From arch's perspective, junk files have two important properties.
First, when copying a tree, the junk files are @emph{not} copied.  Second,
it is considered safe for arch to overwrite a junk file.   In
practice, arch will only ever actually overwrite a junk file if that
junk file has a name that begins with @code{,,}.


@strong{backups} Editor backup files and the backup files created by programs
like @code{patch} often deserve special treatment.   For example, if your
editor creates "numbered backups", those are @emph{almost} junk files,
but rather than deleting all of them, you might want to delete only
some of them.


For arch, what is important is that when copying a tree, backup files
should not also be copied.   For users, what is hopefully most useful
is that using the trick:

@example
@group
        % tla inventory --junk | xargs rm
@end group
@group
@end group
@end example

@noindent
will not delete backup files.


@strong{unrecognized} The appearance in a source tree of a file that doesn't
fit any known pattern (or that has a suspicious name) most likely 
indicates that something has gone wrong.   Rather than silently
ignoring such files or treating them as @code{precious} or @code{junk}, @code{arch} 
explicitly flags these exceptions in order to be able to give 
warnings to users.


Overall, adopting file naming conventions is a discipline that many
programmers may not be accustomed to, but it's one I strongly
recommend.  It's easy to stick to these conventions and tools like
@code{inventory} and @code{tree-lint} (introduced later) help you to keep your
source from get out of control.







