6.1 Customizing the inventory Naming Conventions

In Project Tree Inventories, you learned how the tla inventory command classifies files within a project tree using a set of naming conventions. This appendix explains how you can customize those naming conventions.

6.1.1 When to Customize Naming Conventions

It's best to make customizations to the naming conventions of a project at the outset: before you import your first revision.

If you must make changes later, then it's essential that your changes do not change the classification of files already in the latest revision(s) of your project at the time you make the change (otherwise, you are likely to experience perplexing and undesirable behavior).

6.1.2 How to Customize Naming Conventions

You should begin by reviewing the naming convention algorithm in The arch Naming Conventions in Project Tree Inventories. You can modify that algorithm by changing the regular expression used for each category test.

You can customize naming conventions by modifying the file ./{arch}/=tagging-method in your project trees. That file is created by the id-tagging-method command and initially, it contains a single line which names the id tagging method (names, explicit, tagline (or the now deprecated, but popular in some older projects, including arch itself, implicit)).

In particular, =tagging-method can contain blank lines and comments (lines beginning with #) and directives, one per line. The permissible directives are:

             tagline
             implicit
             explicit
             names
                     specify the id tagging method to use for this tree

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

Regular expressions are specified in Posix ERE syntax (the same syntax used by egrep, grep -E, and awk) and have default values which implement the naming conventions described in The arch Naming Conventions in Project Tree Inventories.

A given regexp directive can occur more than once, in which case the regexps are concatenated as alternatives. Thus, for example:

             source  .*\.c$
             source  .*\.h$

is equivalent to:

             source (.*\.c$)|(.*\.h$)

6.1.3 Per-Directory Regexps

A source directory can contain a .arch-inventory file.

.arch-inventory files can contain regexp declarations just like those in =tagging-method (i.e., one for excludes, one for junk, etc.) Let's call these the dir-local regexps. The =tagging-method regexps are the global regexps.

While traversing a tree, each file is classified-by-name as follows. the steps which are changed by .arch-inventory are marked with [*]:

             0) "." and ".." remain excluded files, no matter what.

        [*]  1) if excluded files are being omitted from the inventory,
                and either the dir-local or global regexp, the file
                is excluded

             2) if the file is a control file, it is source

             3) if the file falls into one of the "mandatory categories"
                (",," and "++" files) it is categorized as junk or
                precious respectively.

        [*]  4) the dir-local (only) regexps are tried in the usual order:
                junk, backup, precious, unrecognized, source.  If the file
                matches, it is suitably categorized.

             5) the global regexps are tried in the same order.

             6) otherwise the file is unrecognized.