File: inventory.html

package info (click to toggle)
arch 1.0pre15-1
links: PTS
area: main
in suites: woody
size: 20,180 kB
ctags: 4,560
sloc: ansic: 64,410; sh: 29,168; lisp: 1,896; awk: 1,044; makefile: 484; sed: 26
file content (1500 lines) | stat: -rw-r--r-- 38,098 bytes
<html>
<head>
<title>arch Project Inventories</title>
</head>
<body>

<a name="arch_Project_Inventories"></a>

<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>

<h2 align=center>arch Project Inventories</h2>




<small>
<b>up: </b><a href="arch.html#arch">arch</a></br>
<b>next: </b><a href="patches.html#arch_Patch_Sets">arch Patch Sets</a></br>

<b>prev: </b><a href="project-trees.html#arch_Project_Trees">arch Project Trees</a></br>

</small>
<br>






<p>In a project tree, some of the files and directories are &quot;part of
the source&quot; -- they are of interest to <code>arch</code>
.  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 by most <code>arch</code>
 commands.
</p><p>This chapter discusses how <code>arch</code>
 recognizes which files to pay
attention to, and which to ignore.
</p><p><code>arch</code>
 has flexible facilities for keeping track of all of the files
and directories in your project: for taking &quot;inventories&quot; of your
project tree.  It has these facilities for three reasons:
</p><p><strong><u>Distinguishing Source</u></strong> <code>arch</code>
 uses a project inventory to
distingiuish files and directories which are part of your project from
other files and directories which are temporary files, scratch files,
editor backup-files, and so forth.
</p><p>Additionally, <code>arch</code>
 permits you to overlay projects: store more than
one project at a single root.  When you do that, <code>arch</code>
 uses
inventories to sort out which files and directories belong to each
project.  (The topic of overlays, however, is deferred until a later
chapter.)
</p><p><strong><u>Recognizing Renames</u></strong> Every file or directory in an <code>arch</code>
 inventory
has two names.  One name is simply the location (path) of the file
relative to the root of the project tree.  The other name is a
&quot;logical name&quot; for the file: a name that remains the same regardless
of where in the project tree the file is located.  When <code>arch</code>

compares two versions of a project tree, it uses logical names to
discover when files or directories have been moved, renamed, deleted,
or added.
</p><p><strong><u>Canonical Inventories</u></strong> Finally, <code>arch</code>
 permits you to make a record
of the &quot;canonical inventory&quot; of your project -- all of the files
that you believe are <strong>supposed</strong> to be there.  <code>arch</code>
 can then tell you
whether any files are missing or have been added compared to the
canonical inventory.
</p><ul>
<li><a href="inventory.html#Choices_Regarding_Inventories">Choices Regarding Inventories</a></li>
<li><a href="inventory.html#Specifying_a_Tagging_Method">Specifying a Tagging Method</a></li>
<li><a href="inventory.html#The_inventory_Command">The inventory Command</a></li>
<li><a href="inventory.html#Using_an_Explicit_Inventory">Using an Explicit Inventory</a></li>
<li><a href="inventory.html#Using_an_Implicit_Inventory">Using an Implicit Inventory</a></li>
<li><a href="inventory.html#Recognizing_Renames_--_Inventory_Tags">Recognizing Renames -- Inventory Tags</a></li>
<li><a href="inventory.html#Keeping_Things_Neat_and_Tidy">Keeping Things Neat and Tidy</a></li>
<li><a href="inventory.html#Avoiding_Accidental_Ommissions_and_Additions">Avoiding Accidental Ommissions and Additions</a></li>
<li><a href="inventory.html#The_Inventory_Tag_Abstraction_in_Detail">The Inventory Tag Abstraction in Detail</a></li>
<li><a href="inventory.html#A_Warning_About_Changing_Tagging_Methods">A Warning About Changing Tagging Methods</a></li>
<li><a href="inventory.html#Other_Ways_to_Tag_Files">Other Ways to Tag Files</a></li>
<li><a href="inventory.html#Telling_tree-lint_to_Shut_Up">Telling tree-lint to Shut Up</a></li>
<li><a href="inventory.html#Which_Tagging_Method_Should_You_Use?">Which Tagging Method Should You Use?</a></li>
<li><a href="inventory.html#Altering_the_Naming_Conventions">Altering the Naming Conventions</a></li>
</ul>

<hr>

<a name="Choices_Regarding_Inventories"></a>



<h3 align=center>Choices Regarding Inventories</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#Specifying_a_Tagging_Method">Specifying a Tagging Method</a></br>


</small>
<br>






<p>For each project tree, you have a choice to make regarding how project
inventories work.  The options are described briefly here, then in
more detail in the sections that follow.
</p><p><strong><u>Naming Conventions</u></strong> The simplest (and default) option is to simply
use <em>
<a name="index-pt:0"></a>

naming conventions
</em>
.  <code>arch</code>
 will search your tree for files
matching certain naming patterns, and consider all of those files to
be source files.
</p><p>When you use only naming conventions to take an inventory, the logical
name of a file and its location name are exactly the same.  For that
reason, if you rename a file, <code>arch</code>
 will think you deleted a file
with the old name, and added a file with the new name.  If you delete
a file, then add a file with the same name, <code>arch</code>
 will think that the
new file is a modified form of the old file.  None of those
limitations are fatal, <code>arch</code>
 will still work, but they do limit the
effectiveness of <code>arch</code>
 at branching and merging.  (&quot;Branching&quot; and
&quot;merging&quot; are topics of a later chapter.)
</p><p><strong><u>Explicit Inventories</u></strong> Another option is to use an <em>
<a name="index-pt:1"></a>

explicit inventory
</em>
.
Once again, <code>arch</code>
 will search for files that satisfy certain naming
conventions -- but not every such file or directory is automatically
source.  Instead, whenever you add, delete or renamed a file, you must
inform <code>arch</code>
 of that fact explicitly.  For example, after adding the
file <code>foo.c</code>
, you have to tell <code>arch</code>
:
</p><pre>
        % larch add foo.c

</pre>
<p>and if you rename <code>foo.c</code>
 to <code>bar.c</code>
, then you must also tell <code>arch</code>
:
</p><pre>
        % larch move foo.c bar.c

</pre>
<p><strong><u>Implicit Inventories</u></strong> A third option combines some of the advantages
of using naming conventions with some of the advantages of explicit
inventories: <em>
<a name="index-pt:2"></a>

implicit inventories
</em>
.  When you use an implicit
inventory, every file that passes the naming conventions is considered
source.  You <strong>may</strong> explicitly add, delete, and rename files --
allowing <code>arch</code>
 to precisely track renames for those files and
directories.  You also <strong>may</strong> store a <em>
<a name="index-pt:3"></a>

file tag
</em>
 (the &quot;logical name&quot;
of a file) <em>in</em> any file.  If you don't explicitly tag a file, and use
an implicit inventory, <code>arch</code>
 will search for those embedded tags and
use them to precisely detect new files, deleted files, and renamed
files.
</p><p>Each of the three options is called a <em>
<a name="index-pt:4"></a>

tagging method
</em>
.
</p><p>There is some advice at the end of this chapter about how to choose
among the three tagging methods.
</p>










<hr>

<a name="Specifying_a_Tagging_Method"></a>



<h3 align=center>Specifying a Tagging Method</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#The_inventory_Command">The inventory Command</a></br>

<b>prev: </b><a href="inventory.html#Choices_Regarding_Inventories">Choices Regarding Inventories</a></br>

</small>
<br>






<p><a name="index-pt:5"></a>

</p><p>If you never explicitly specify a tagging method, <code>arch</code>
 will use
simple naming conventions, by default.  You can also make explicit
your choice to use only naming conventions with this command issued in
a project tree:
</p><pre>
        % larch tagging-method names

</pre>
<p>Similarly, to use either an implicit or explicit inventory, use one of
the commands:
</p><pre>
        % larch tagging-method explicit
        % larch tagging-method implicit

</pre>
<p>To find out what method a given project tree uses, use the same
command with no argument:
</p><pre>
        % larch tagging-method
        names

</pre>











<hr>

<a name="The_inventory_Command"></a>



<h3 align=center>The inventory Command</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#Using_an_Explicit_Inventory">Using an Explicit Inventory</a></br>

<b>prev: </b><a href="inventory.html#Specifying_a_Tagging_Method">Specifying a Tagging Method</a></br>

</small>
<br>






<p><a name="index-pt:6"></a>

</p><p>The command <code>larch inventory</code>
 is used to print a list of source files.
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):
</p><pre>
        % cd source-tree

</pre>
<pre>
        % larch inventory --source
        hello.c
        hello.h
        library
        library/buffer.c
        library/buffer.h
        ...

</pre>
<p>contrasted with:
</p><pre>
        % cd source-tree

</pre>
<pre>
        % ls
        hello.c   hello.c.~1~   hello.h  library

</pre>
<p>(Notice that <code>hello.c.~1~</code>
 is not included in the inventory of
source files.)
</p><p>The naming conventions used by <code>arch</code>
 are as follows:
</p><p><strong><u>Control Files</u></strong> A <em>
<a name="index-pt:7"></a>

control file
</em>
 <em>is</em> part of the source, but control
files are not included in the output of <code>larch inventory</code>
 unless the
<code>--all</code>
 flag is used.  Control file and directory names match any of
these patterns:
</p><pre>
        .arch-project-tree
        .arch-ids
        .owned.*
        .common
        {arch}

</pre>
<p><strong><u>Junk Files</u></strong> A <em>
<a name="index-pt:8"></a>

junk file
</em>
 is <em>not</em> part of the source.  A junk file
or directory name matches the pattern:
</p><pre>
        ,*

</pre>
<p>or if it contains any of the characters:
</p><pre>
        &lt;space>
        &lt;tab>
        &lt;newline>
        [
        ]

</pre>
<pre>
        ?
        \

</pre>
<p>Note that if a directory name matches that pattern, then none of the
contents of the directory are part of the source, regardless of their
names.
</p><p>Junk files are listed by the command:
</p><pre>
        % larch inventory --junk

</pre>
<p>Arch sometimes creates junk files and directories of its own.  When it
does, those files and directories have names that match the pattern:
</p><pre>
        ,,*

</pre>
<p>You should avoid creating files and directories with names that match
that pattern.  <code>arch</code>
 will freely delete files and directories with
names that match <code>,,*</code>
 whenever it needs to re-use such a name.
</p><p>Usually, <code>arch</code>
 will delete any junk file it creates before the
command that created the junk file terminates.  Sometimes, though,
when a command fails, <code>arch</code>
 will leave behind junk files or
directories matching <code>,,*</code>
.  This is a debugging feature, likely to be
removed in a future release.  For now, whenever you find such a file
(and are confident it isn't being used by a currently running
command), you are free to delete it.
</p><p><strong><u>Backup Files</u></strong> If a file is not a junk file, it may be a <em>
<a name="index-pt:9"></a>

backup
file
</em>
.  Backup files are not part of the source.  They match any of
the patterns:
</p><pre>
      *~
      *.bak
      *.modified
      *.orig
      *.original
      *.rej
      *.rejects

</pre>
<p>Backup files are listed by the command:
</p><pre>
        % larch inventory --backups

</pre>
<p><strong><u>Precious Files</u></strong> If a file is not a control file, junk file, or backup
file, it might be a <em>
<a name="index-pt:10"></a>

precious file
</em>
.  Precious files are not part of
the source, but <code>arch</code>
 does sometimes treat them specially.  For
example, when <code>arch</code>
 copies a directory of source for you, it copies
not only the source files, but the precious files as well.
</p><p>Precious files and directories match one of these patterns:
</p><pre>
        +*
        .gdbinit
        =build*
        =install*
        CVS
        RCS
        TAGS

</pre>
<p>Of course, precious files can be listed by the command:
</p><pre>
        % larch inventory --precious

</pre>
<p>Sometimes <code>arch</code>
 will create its own precious files -- usually to save
some information that you might not want to lose.  When it does, it
creates a file or directory matching the pattern:
</p><pre>
        ++*

</pre>
<p>You should avoid creating such filenames yourself.  <code>arch</code>
 won't every
delete such a file -- but if one happens to get in the way of an
<code>arch</code>
 command, that command will fail with an error.
</p><p><strong><u>Source Files</u></strong> If a file is not a control, junk, backup, or precious
file, it might be an ordinary <em>
<a name="index-pt:11"></a>

source file
</em>
.  Source files are, of
course, the files that <code>arch</code>
 stores in an archive (along with control
files).
</p><p>Source files must match the pattern:
</p><pre>
        [=a-zA-Z0-9]*

</pre>
<p>but must <em>not</em> match any of the patterns:
</p><pre>
      *.o
      *.core
      core

</pre>
<p>Ordinary source files are listed by:
</p><pre>
        % larch inventory --source

</pre>
<p>Some files which are <code>arch</code>
 control files are counted as source even
though they don't match the patterns above.  However, these files are
not listed by default.  All source files (ordinary source plus control
files) are listed by:
</p><pre>
        % larch inventory --source --all

</pre>
<p><strong><u>Unrecognized Files</u></strong>  Any file that doesn't fall into the above
categories is an <em>
<a name="index-pt:12"></a>

unrecognized file
</em>
.  Unrecognized files can be
listed by the command:
</p><pre>
       % larch inventory --unrecognized

</pre>
<p><strong><u>WARNING</u></strong> The basic pattern for source files is:
</p><pre>
        [=a-zA-Z]*

</pre>
<p>however, you should restrict yourself to file names that do not
contain spaces.  Filenames containing spaces are likely to trigger
bugs in the current release of <code>arch</code>
.
</p>










<hr>

<a name="Using_an_Explicit_Inventory"></a>



<h3 align=center>Using an Explicit Inventory</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#Using_an_Implicit_Inventory">Using an Implicit Inventory</a></br>

<b>prev: </b><a href="inventory.html#The_inventory_Command">The inventory Command</a></br>

</small>
<br>






<p><a name="index-pt:13"></a>

<a name="index-pt:14"></a>

<a name="index-pt:15"></a>

<a name="index-pt:16"></a>

</p><p>If you want to use explicit designation of source filess, rather than
naming conventions alone, then use this command:
</p><pre>
        % larch tagging-method explicit

</pre>
<p>Note that you must use that command from within a working directory
tree that has already been initialized using <code>init</code>
.
</p><p>When using explicit designation, it is (ordinarilly) necessary to add
every file and directory in the source to the explicit list using the
command:
</p><pre>
        % larch add FILE

</pre>
<p>If <code>FILE</code>
 is a directory, that will create <code>FILE/.arch_ids/=id</code>
.  If
it is a regular file or symbolic link, it will create (in the same
directory) <code>.arch_ids/FILE.id</code>
.  In either case, the file created will
contain an obscure string known as an &quot;inventory tag&quot; (inventory
tags are explained in more detail below).
</p><p>If you remove a regular file or symbolic link, you must use the
command:
</p><pre>
        % larch delete FILE

</pre>
<p>That won't remove <code>FILE</code>
 itself, but it will remove the inventory tag
for <code>FILE</code>
.
</p><p>In order to remove a directory, you must yourself remove the
<code>.arch_ids</code>
 subdirectory.  That will also implicitly remove the
inventory tags of any files that <code>arch</code>
 thinks are stored in that
directory.
</p><p>If you rename a regular file or symbolic link, you can use the
command:
</p><pre>
        % larch move OLD-NAME NEW-NAME

</pre>
<p>to move the inventory tag for that file.
</p><p>If you rename a directory, it's inventory tag (and the tags for all
files and subdirectories it contains) move with it automatically
(because the <code>.arch_ids</code>
 subdirectory has moved).
</p><p>When you run <code>larch inventory</code>
 in a working directory using explicit
designation, 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:
</p><pre>
        % larch inventory --source --names

</pre>
<p>You should also read about <code>tree-lint</code>
 later in this chapter.
</p>










<hr>

<a name="Using_an_Implicit_Inventory"></a>



<h3 align=center>Using an Implicit Inventory</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#Recognizing_Renames_--_Inventory_Tags">Recognizing Renames -- Inventory Tags</a></br>

<b>prev: </b><a href="inventory.html#Using_an_Explicit_Inventory">Using an Explicit Inventory</a></br>

</small>
<br>






<p><a name="index-pt:17"></a>

</p><p>To use implicit tagging, use the following command in your working
directory:
</p><pre>
        % larch tagging-method implicit

</pre>
<p>When implicit tagging is used, every file that passes the naming
conventions is treated as source.  If a file or directory has an
explicit tag (created with <code>add</code>
), <code>arch</code>
 will use that explicit
tag to recognize when a file has moved.  If a file (but not a
directory or symbolic link) lacks an explicit tag, <code>arch</code>
 will look
for a tag in the file itself.
</p><p>A tag within a file has one of two forms.  It may be either:
</p><pre>
        &lt;punct>&lt;basename>&lt;spaces>-&lt;spaces>&lt;tag>

</pre>
<p>where <code>&lt;punct></code>
 is an arbitrary string of punctuation and spaces,
<code>&lt;basename></code>
 is the basename of the file, and <code>&lt;tag></code>
 an inventory tag
for the file.  Or:
</p><pre>
        &lt;punct>tag:&lt;spaces>&lt;tag>

</pre>
<p>In either case, <code>&lt;tag></code>
 should be unique among the files within a
directory.  A tag within a file must occur within the first <code>1024</code>
 bytes
of the file.
</p><p>A handy convention for source files is to add a comment to the top of
every file, briefly stating the purpose of the file:
</p><pre>
        /* hello.c - `main' for the hello world program
...

</pre>
<p>or:
</p><pre>
        /* tag: `main' for the hello world program
...

</pre>
<p>Another possible convention is to use a string identifying the author
and the time the file was first created (or first tagged):
</p><pre>
        /* tag: joe.hacker@gnu.org Thu Nov 29 17:25:15 PST 2001
...

</pre>
<p>If you use the <code>basename</code>
 form of an implicit tag, and actually rename
a file (rather than simply move it between directories), you do need
to remember to update the tag line to reflect the new basename.
</p><p>When you use implicit tagging, it is ok if a file lacks any tag at
all, either explicit or implicit.  In that case, if you rename the
file, <code>arch</code>
 will think you've deleted the old file and added a new
one -- but aside from that, everything will work normally.
</p><p><strong><u>CAUTION:</u></strong> 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>_</code>
.  For example, you write the that tag:
</p><pre>
        `main' for the hello    world program

</pre>
<p>the actual inventory tag is:
</p><pre>
        `main'_for_the_hello____world_program

</pre>
<p>It is possible that a future release of <code>arch</code>
 will slightly change
the rule -- so that multiple spaces and tabs are replaced by a single
<code>_</code>
.
</p>










<hr>

<a name="Recognizing_Renames_--_Inventory_Tags"></a>



<h3 align=center>Recognizing Renames -- Inventory Tags</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#Keeping_Things_Neat_and_Tidy">Keeping Things Neat and Tidy</a></br>

<b>prev: </b><a href="inventory.html#Using_an_Implicit_Inventory">Using an Implicit Inventory</a></br>

</small>
<br>






<p><a name="index-pt:18"></a>

<a name="index-pt:19"></a>

</p><p>If you are using naming conventions only to recognize source files,
then if you rename a directory or file, <code>arch</code>
 will conclude that you
have deleted the old file, and created a new file.
</p><p>If you are using an explicit source inventory, <code>arch</code>
 will always
recognize when a directory is renamed (presuming that the <code>.arch_ids</code>

subdirectory is preserved), and it will recognize when a file is
renamed if you use <code>move</code>
 (rather than <code>delete</code>
 and <code>add</code>
).
Of course, <code>arch</code>
 can be fooled if you swap two files without swapping
their inventory tags.
</p><p>If you are using an implicit inventory, <code>arch</code>
 will never recognize
when an untagged file is renamed (it will think &quot;delete&quot; and
&quot;add&quot;).  If a file is tagged explicitly, <code>arch</code>
 will recognize when
the file is added, deleted, or renamed -- just as when using an
explicit inventory.  If a file is not tagged explicitly, but has an
embedded tag, <code>arch</code>
 will recognize when the file is added, deleted or
moved.
</p>










<hr>

<a name="Keeping_Things_Neat_and_Tidy"></a>



<h3 align=center>Keeping Things Neat and Tidy</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#Avoiding_Accidental_Ommissions_and_Additions">Avoiding Accidental Ommissions and Additions</a></br>

<b>prev: </b><a href="inventory.html#Recognizing_Renames_--_Inventory_Tags">Recognizing Renames -- Inventory Tags</a></br>

</small>
<br>






<p><a name="index-pt:20"></a>

</p><p>The command:
</p><pre>
        % larch tree-lint

</pre>
<p>is useful for keeping things neat and tidy.
</p><p>If you use 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.
</p><p>If you use 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.
</p><p>In either case, or if you are using naming conventions only,
<code>tree-lint</code>
 will tell you of any files that don't fit the naming
conventions at all.
</p><p>Finally, if you use explicit or implicit tagging, <code>tree-lint</code>
 will
check for cases where multiple files use the same tag.  If any two
files do have the same tag, you <strong>must</strong> correct that, either by
editting the tag (if it is in the file itself) or by using <code>delete</code>

and <code>add</code>
 to replace a duplicated explicit tag.
</p>










<hr>

<a name="Avoiding_Accidental_Ommissions_and_Additions"></a>



<h3 align=center>Avoiding Accidental Ommissions and Additions</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#The_Inventory_Tag_Abstraction_in_Detail">The Inventory Tag Abstraction in Detail</a></br>

<b>prev: </b><a href="inventory.html#Keeping_Things_Neat_and_Tidy">Keeping Things Neat and Tidy</a></br>

</small>
<br>






<p><a name="index-pt:21"></a>

<a name="index-pt:22"></a>

<a name="index-pt:23"></a>

</p><p>A <em>
<a name="index-pt:24"></a>

manifest
</em>
 is an explicit list of the files you believe are
<strong>supposed</strong> to be in a project tree.  <code>arch</code>
 allows you to maintain a
manifest, and to compare it to the actual contents of a tree.
</p><p>The command <code>set-manifest</code>
 sets the manifest to the current contents
of the project tree:
</p><pre>
        % larch set-manifest

</pre>
<p>Note that only regular source files, not <code>arch</code>
 control files, are
included in the manifest.  To replace an existing manifest, you must
provide the <code>-f</code>
 flag (or <code>--force</code>
) to <code>set-manifest</code>
.
</p><p>You can retrieve the manifest with:
</p><pre>
        % larch manifest

</pre>
<p>Each line of the manifest is of the form:
</p><pre>
        &lt;path>\t&lt;tag>

</pre>
<p>and the list is sorted by the <code>&lt;tag></code>
 field.
</p><p>You can look for missing, added, or renamed files with:
</p><pre>
        % larch check-manifest

</pre>
<p>which will compare the project tree inventory to the manifest and
print a report describing divergences (if there are any).
</p>










<hr>

<a name="The_Inventory_Tag_Abstraction_in_Detail"></a>



<h3 align=center>The Inventory Tag Abstraction in Detail</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#A_Warning_About_Changing_Tagging_Methods">A Warning About Changing Tagging Methods</a></br>

<b>prev: </b><a href="inventory.html#Avoiding_Accidental_Ommissions_and_Additions">Avoiding Accidental Ommissions and Additions</a></br>

</small>
<br>






<p>When <code>arch</code>
 considers the files and directories in a working directory
it builds a one-to-one index mapping path names (relative to the root
of the working directory tree) to <em>
<a name="index-pt:25"></a>

inventory tags
</em>
.
</p><p>The inventory tag of a file is its &quot;logical identity&quot;.  The path is
the position of that identity within the particular working dir.
</p><p>You can see the inventory tag for each source file with the command:
</p><pre>
        % larch inventory --source --tags

</pre>
<p>When <code>arch</code>
 compares two project trees, it bases the comparison on
logical identities.  If both trees have a file with a particular
inventory tag, but the files are in different positions, then <code>arch</code>

considers the file to have been moved or renamed.  Similarly, if an
inventory tag is present in one tree, but missing in the other, then
<code>arch</code>
 considers the file to have been added or deleted.
</p><p>If you use naming conventions only, the inventory tag of each file is
the same as its path.  Thus, when using the <code>names</code>
 tagging method,
<code>arch</code>
 never recognizes that a file has been moved or renamed.
</p><p>When you use the <code>explicit</code>
 tagging method, inventory tags are stored
in the <code>.arch-ids</code>
 directories.  There is a file in <code>.arch-ids</code>
 for
each tagged file (and one file for the directory containing
<code>.arch-ids</code>
), and those files contain the tags.
</p><p>When you use the <code>implicit</code>
 tagging method, tags in <code>.arch-ids</code>

directories take precedence (if they exist).  If a file is not
explicitly tagged, <code>arch</code>
 searches for the inventory tag in the file
itself (as described earlier in the chapter).  Finally, if a file is
not tagged at all, then its path is used as the inventory tag.
</p>










<hr>

<a name="A_Warning_About_Changing_Tagging_Methods"></a>



<h3 align=center>A Warning About Changing Tagging Methods</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#Other_Ways_to_Tag_Files">Other Ways to Tag Files</a></br>

<b>prev: </b><a href="inventory.html#The_Inventory_Tag_Abstraction_in_Detail">The Inventory Tag Abstraction in Detail</a></br>

</small>
<br>






<p>Be cautious when changing tagging methods for directories already
checked-in to an <code>arch</code>
 revision control archive.
</p><p>For example, if you change from the tagging method <code>names</code>
 to
<code>explicit</code>
, then the inventory tag for every file will change.  <code>arch</code>

will think that you've deleted all of the files in the old tree, and
added all of the files in the new tree.
</p><p>However, there is a work-around for this problem, described in a later
chapter.
</p>










<hr>

<a name="Other_Ways_to_Tag_Files"></a>



<h3 align=center>Other Ways to Tag Files</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#Telling_tree-lint_to_Shut_Up">Telling tree-lint to Shut Up</a></br>

<b>prev: </b><a href="inventory.html#A_Warning_About_Changing_Tagging_Methods">A Warning About Changing Tagging Methods</a></br>

</small>
<br>






<p><a name="index-pt:26"></a>

</p><p>In some situations, it isn't convenient to explicitly tag every file
or to add an implicit tag to every file.
</p><p>You can supply a <em>
<a name="index-pt:27"></a>

default tag
</em>
 for every file that doesn't have an
explicit tag with the command:
</p><pre>
        % larch explicit-default TAG-PREFIX

</pre>
<p>After that, every file in that directory which lacks an explicit tag
will have the tag:
</p><pre>
        TAG-PREFIX__BASENAME

</pre>
<p>where <code>BASENAME</code>
 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:
</p><pre>
        % larch explicit-default
        TAG-PREFIX

</pre>
<p>and remove the default with:
</p><pre>
        % larch explicit-default --delete

</pre>
<p>You can also specify a default tag which has <em>lower</em> precedence than
implicit tags:
</p><pre>
        % larch explicit-default --weak TAG-PREFIX

</pre>
<p>and view that default:
</p><pre>
        % larch explicit-default --weak

</pre>
<p>or delete it:
</p><pre>
        % larch explicit-default --weak --delete

</pre>











<hr>

<a name="Telling_tree-lint_to_Shut_Up"></a>



<h3 align=center>Telling tree-lint to Shut Up</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#Which_Tagging_Method_Should_You_Use?">Which Tagging Method Should You Use?</a></br>

<b>prev: </b><a href="inventory.html#Other_Ways_to_Tag_Files">Other Ways to Tag Files</a></br>

</small>
<br>






<p><a name="index-pt:28"></a>

<a name="index-pt:29"></a>

</p><p>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</code>
.  There are two ways to tell <code>tree-lint</code>
 to shut-up
about such files:
</p><p>One is to provide a default explicit tag or weak default explicit tag
using <code>larch explicit-default</code>
, as described above.  
</p><p>The second method is to label the directory as &quot;don't care&quot;
directory -- which means that <code>tree-lint</code>
 shouldn't complain about
untagged files.  You can do that with:
</p><pre>
        % larch explicit-default --dont-care set

</pre>
<p>or remove the &quot;don't care&quot; flag with:
</p><pre>
        % larch explicit-default --delete --dont-care

</pre>
<p>You can find out whether the &quot;don't care&quot; flag is set in a given
directory with:
</p><pre>
        % larch explicit-default --dont-care

</pre>











<hr>

<a name="Which_Tagging_Method_Should_You_Use?"></a>



<h3 align=center>Which Tagging Method Should You Use?</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
<b>next: </b><a href="inventory.html#Altering_the_Naming_Conventions">Altering the Naming Conventions</a></br>

<b>prev: </b><a href="inventory.html#Telling_tree-lint_to_Shut_Up">Telling tree-lint to Shut Up</a></br>

</small>
<br>






<p>Given the choice of the <code>names</code>
, <code>explicit</code>
, and <code>implicit</code>
 tagging
conventions, which one should you choose?
</p><p>The <code>names</code>
 method is best for project trees that you don't control,
and for which the maintainer does not include file tags (either
explicit or implicit).  For such trees, the <code>names</code>
 method will always
work, but if you want to use the <code>explicit</code>
 or <code>implicit</code>
 method,
you'll have to add file tags yourself.
</p><p>The <code>implicit</code>
 method is, in my opinion, by far the most convenient.
It is easy to get in the habit of adding a <code>tag:</code>
 line to the bottom
of each new file and doing a single <code>larch add</code>
 for each directory.
After those steps, you can rename files and directories freely --
without having to remember to tell <code>arch</code>
 in a separate command.
</p><p>On the other hand, the <code>implicit</code>
 method has two limitations.  One
limitation is that you must accept the possibility of accidently
adding new files to the inventory.  Any file you create that passes
the naming conventions counts as source.  The other, closely related,
limitation is that if you use <code>implicit</code>
 inventories, you will
<strong>never</strong> want to compile a program in its own source directory.  When
you compile a program, that creates intermediate files and
executables.  Many of those files will almost certainly pass the
naming conventions for source -- so <code>arch</code>
 will wrongly include them
in a source inventory.  I use the <code>implicit</code>
 method, but my
<code>configure</code>
 scripts have a safeguard that causes them to refuse to
compile my programs in the source tree.
</p><p>Finally, the <code>explicit</code>
 method is the only choice left if you want the
benefits of real file tags (therefore you can't use the <code>names</code>

method) but either insist on compiling in the source tree or can't
risk accidently adding the occasional unintended file (so you
shouldn't use <code>implicit</code>
).
</p>










<hr>

<a name="Altering_the_Naming_Conventions"></a>



<h3 align=center>Altering the Naming Conventions</h3>




<small>
<b>up: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>

<b>prev: </b><a href="inventory.html#Which_Tagging_Method_Should_You_Use?">Which Tagging Method Should You Use?</a></br>

</small>
<br>






<p><strong><u>Note:</u></strong> this is a relatively new feature, so the documentation is not
yet well integrated with the rest of the manual.
</p><p>The file <code>{arch}/=tagging-method</code>
 defines the naming conventiosn used
for a particular project tree.  By editting that file, you can
estalish naming conventions that are different from the defaults,
which are described above.
</p><p>That file can contain blank lines and comments (lines beginning with
<em>
<a name="index-pt:30"></a>

#
</em>
) and directives, one per line.  The permissable directives are:
</p><pre>
        implicit
        explicit
        names
                specify the tagging method to use for this tree

</pre>
<pre>
        exclude RE
        junk RE
        backup RE
        precious RE
        unrecognized RE
        source RE
                specify a regular expression to use for the indicated
                category of files.

</pre>
<p>Regular expressions are specified in Posix ERE syntax (the same syntax
used by <em>
<a name="index-pt:31"></a>

egrep
</em>
, <em>
<a name="index-pt:32"></a>

grep -E
</em>
, and <em>
<a name="index-pt:33"></a>

awk
</em>
) and have default values which
implement the naming conventions described above.
</p><p>The <code>exclude</code>
 pattern should match a subset of files matched by the
<code>source</code>
 pattern.  Files which match <code>exclude</code>
 are printed by:
</p><pre>
        % larch inventory --source --all

</pre>
<p>but not printed by:
</p><pre>
        % larch inventory --source

</pre>
<p>Although you can define your own naming conventions, there are some
minor limitations:
</p><p>The file names <code>.</code>
 and <code>..</code>
 are always ignored by <code>inventory</code>
.
</p><p>File names which contain non-printing characters, spaces, or any of
the globbing characters (<code>*</code>
, <code>[</code>
, <code>]</code>
, <code>\</code>
, <code>?</code>
) are always placed
in the category <code>unrecognized</code>
.  This is so that tools which operate
on project trees can safely presume that no source file has a name
that includes these characters.
</p><p>File names which begin with <em>
<a name="index-pt:34"></a>

,,
</em>
 are always placed in the category
<code>junk</code>
.  This is so that tools which operate on a project tree can
safely destroy or create files beginning with <em>
<a name="index-pt:35"></a>

,,
</em>
.
</p><p>The default naming conventions are given by:
</p><pre>
       exclude ^(.arch-ids|\{arch\})$
       junk ^(,.*)$
       backup ^.*(~|\.~[0-9]+~|\.bak|\.orig|\.rej|\.original|\.modified|\.reject)$
       precious ^(\+.*|\.gdbinit|=build\.*|=install\.*|CVS|CVS\.adm|RCS|RCSLOG|SCCS|TAGS)$
       unrecognized ^(.*\.(o|a|so|core)|core)$
       source ^([_=a-zA-Z0-9].*|\.arch-ids|\{arch\}|\.arch-project-tree)$

</pre>



















<small><i>arch: The arch Revision Control System

</i></small><br>


<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>

</body>