Knowledge base CVS — Concurrent Versions System

Modules

The administrative files

• Taken from Section 2.4 of CVS Manual

The directory ‘$CVSROOT/CVSROOT’ contains some administrative files. [...] The most important of these files is the ‘modules’ file. It defines all modules in the repository. This is a sample ‘modules’ file.

CVSROOT CVSROOT
modules CVSROOT modules
cvs gnu/cvs
rcs gnu/rcs
diff gnu/diff
tc yoyodyne/tc

The ‘modules’ file is line oriented. In its simplest form each line contains the name of the module, whitespace, and the directory where the module resides. The directory is a path relative to $CVSROOT. The last four lines in the example above are examples of such lines.
The line that defines the module called ‘modules’ uses features that are not explained here. See [[http://ftp.gnu.org/non-gnu/cvs/source/feature/1.12.9/cederqvist-1.12.9.pdf][Section C.1 [modules], page 139]], for a full explanation of all the available features.

NOTE: Editing administrative files

You edit the administrative files in the same way that you would edit any other module. Use ‘cvs checkout CVSROOT’ to get a working copy, edit it, and commit your changes in the normal way.
It is possible to commit an erroneous administrative file. You can often fix the error and check in a new revision, but sometimes a particularly bad error in the administrative file makes it impossible to commit new revisions. If and when this happens, you can correct the problem by temporarily copying a corrected administrative file directly into the $CVSROOT/CVSROOT repository directory, then committing the same correction via a checkout of the ‘CVSROOT’ module. It is important that the correction also be made via the checked out copy, or the next checkout and commit to the CVSROOT module will overwrite the correction that was copied directly into the repository, possibly breaking things in such a way as to prevent commits again.

The module file

• Taken from [[http://ftp.gnu.org/non-gnu/cvs/source/feature/1.12.9/cederqvist-1.12.9.pdf][Section C.1 [modules], page 139]]

The ‘modules’ file records your definitions of names for collections of source code. cvs will use these definitions if you use cvs 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: cvs 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 cvs 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 cvs 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 firstdir, 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 cvs 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 cvs.

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’.

Troubleshooting