Appendix B. Reference manual for Administrative files

Table of Contents

The modules file
Alias modules
Regular modules
Ampersand modules
Excluding directories
Module options
How the modules file "program options" programs are run
The modules2 file
How the modules2 file differs from the modules file
Modules2 syntax
The cvswrappers file
default wrappers
The commit support files
The common syntax
Triggers
Commitinfo
Verifying
Loginfo
Loginfo example
Loginfo default standard input format
Precommand
postcommand
premodule
postmodule
postcommit
historyinfo
rcsinfo
notify
keywords
Storing user defined information using keywords
Email notification
Configure the commit support files
Write the template
Configure the server
Keywords used in template files
Ignoring files via cvsignore
The checkoutlist file
The history file
The shadow file
Keeping a checked out copy
ActiveScript support
Expansions in administrative files
The CVSROOT/config configuration file
The server configuration files

Inside the repository, in the directory $REAL_CVSROOT/CVSROOT, there are a number of supportive files for cvsnt. You can use cvsnt in a limited fashion without any of them, but if they are set up properly they can help make life easier. For a discussion of how to edit them, see the section called “The administrative files”.

The most important of these files is the modules file, which defines the modules inside the repository.

The modules file

The modules file records your definitions of names for collections of source code. cvsnt will use these definitions if you use cvsnt to update the modules file (use normal commands like add, commit, etc).

The modules file may contain blank lines and comments (lines beginning with #) as well as module definitions. Long lines can be continued on the next line by specifying a backslash (\) as the last character on the line.

There are three basic types of modules: alias modules, regular modules, and ampersand modules. The difference between them is the way that they map files in the repository to files in the working directory. In all of the following examples, the top-level repository contains a directory called first-dir, which contains two files, file1 and file2, and a directory sdir. first-dir/sdir contains a file sfile.

Alias modules

Alias modules are the simplest kind of module:

mname -a aliases...

This represents the simplest way of defining a module mname. The -a flags the definition as a simple alias: cvsnt will treat any use of mname (as a command argument) as if the list of names aliases had been specified instead. aliases may contain either other module names or paths. When you use paths in aliases, checkout creates all intermediate directories in the working directory, just as if the path had been specified explicitly in the cvsnt arguments.

For example, if the modules file contains:

amodule -a first-dir

then the following two commands are equivalent:

$ cvs co amodule
$ cvs co first-dir

and they each would provide output such as:

cvs checkout: Updating first-dir
U first-dir/file1
U first-dir/file2
cvs checkout: Updating first-dir/sdir
U first-dir/sdir/sfile

Regular modules

mname [ options ] dir [ files... ]

In the simplest case, this form of module definition reduces to mname dir. This defines all the files in directory dir as module mname. dir is a relative path (from $CVSROOT) to a directory of source in the source repository. In this case, on checkout, a single directory called mname is created as a working directory; no intermediate directory levels are used by default, even if dir was a path involving several directory levels.

For example, if a module is defined by:

regmodule first-dir

then regmodule will contain the files from first-dir:

$ cvs co regmodule
cvs checkout: Updating regmodule
U regmodule/file1
U regmodule/file2
cvs checkout: Updating regmodule/sdir
U regmodule/sdir/sfile
$

By explicitly specifying files in the module definition after dir, you can select particular files from directory dir. Here is an example:

regfiles first-dir/sdir sfile

With this definition, getting the regfiles module will create a single working directory regfiles containing the file listed, which comes from a directory deeper in the cvsnt source repository:

$ cvs co regfiles
U regfiles/sfile
$

Ampersand modules

A module definition can refer to other modules by including &module in its definition.

mname [ options ] &module...

Then getting the module creates a subdirectory for each such module, in the directory containing the module. For example, if modules contains

ampermod &first-dir

then a checkout will create an ampermod directory which contains a directory called first-dir, which in turns contains all the directories and files which live there. For example, the command

$ cvs co ampermod

will create the following files:

ampermod/first-dir/file1
ampermod/first-dir/file2
ampermod/first-dir/sdir/sfile

There is one quirk/bug: the messages that cvsnt prints omit the ampermod, and thus do not correctly display the location to which it is checking out the files:

$ cvs co ampermod
cvs checkout: Updating first-dir
U first-dir/file1
U first-dir/file2
cvs checkout: Updating first-dir/sdir
U first-dir/sdir/sfile
$

Do not rely on this buggy behavior; it may get fixed in a future release of cvsnt.

Excluding directories

An alias module may exclude particular directories from other modules by using an exclamation mark (!) before the name of each directory to be excluded.

For example, if the modules file contains:

exmodule -a !first-dir/sdir first-dir

then checking out the module exmodule will check out everything in first-dir except any files in the subdirectory first-dir/sdir.

Module options

Either regular modules or ampersand modules can contain options, which supply additional information concerning the module.

-d name

Name the working directory something other than the module name.

-e prog

Specify a program prog to run whenever files in a module are exported. prog runs with a single argument, the module name.

-i prog

Specify a program prog to run whenever files in a module are committed. prog runs with a single argument, the full pathname of the affected directory in a source repository. The commitinfo, loginfo, and verifymsg files provide other ways to call a program on commit.

-o prog

Specify a program prog to run whenever files in a module are checked out. prog runs with a single argument, the module name.

-s status

Assign a status to the module. When the module file is printed with cvs checkout -s the modules are sorted according to primarily module status, and secondarily according to the module name. This option has no other meaning. You can use this option for several things besides status: for instance, list the person that is responsible for this module.

-t prog

Specify a program prog to run whenever files in a module are tagged with rtag. prog runs with two arguments: the module name and the symbolic tag specified to rtag. It is not run when tag is executed. Generally you will find that taginfo is a better solution (the section called “User-defined logging”).

How the modules file "program options" programs are run

For checkout, rtag, and export, the program is server-based, and as such the following applies:-

If using remote access methods (pserver, ext, etc.), cvsnt will execute this program on the server from a temporary directory. The path is searched for this program.

If using "local access" (on a local or remote NFS filesystem, i.e. repository set just to a path), the program will be executed from the newly checked-out tree, if found there, or alternatively searched for in the path if not.

The programs are all run after the operation has effectively completed.