Inside the repository, in the directory `$CVSROOT/CVSROOT', there are a number of supportive files for CVS. You can use CVS 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 section The administrative files.
The most important of these files is the `modules' file, which defines the modules inside the repository.
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 are the simplest kind of module:
mname -a 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
mname [ options ] dir [ files... ]
$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 $
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 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.
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'.
Either regular modules or ampersand modules can contain options, which supply additional information concerning the module.
-d name
-e prog
-i prog
-o prog
-s status
-t prog
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 (see section User-defined logging).
-u prog
You should also see see section How the modules file "program options" programs are run about how the "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.), CVS 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 commit and update programs are locally-based, and are run as follows:-
The program is always run locally. One must re-checkout the tree one is using if these options are updated in the modules administrative file. The file CVS/Checkin.prog contains the value of the option `-i' set in the modules file, and similarly for the file CVS/Update.prog and `-u'. The program is always executed from the top level of the checked-out copy on the client. Again, the program is first searched for in the checked-out copy and then using the path.
Note also that the commit and update programs work ONLY when using local repository access -- the files simply aren't created when sources are checked out from a pserver or other remote CVS.
The programs are all run after the operation has effectively completed.
Wrappers refers to a CVS feature which lets you control certain settings based on the name of the file which is being operated on. The settings are `-k' for binary files, and `-m' for nonmergeable text files.
The `-m' option
specifies the merge methodology that should be used when
a non-binary file is updated. MERGE means the usual
CVS behavior: try to merge the files. COPY
means that cvs update will refuse to merge
files, as it also does for files specified as binary
with `-kb' (but if the file is specified as
binary, there is no need to specify `-m 'COPY'').
CVS will provide the user with the
two versions of the files, and require the user using
mechanisms outside CVS, to insert any necessary
changes. WARNING: do not use COPY with
CVS 1.9 or earlier--such versions of CVS will
copy one version of your file over the other, wiping
out the previous contents.
The `-m' wrapper option only affects behavior when
merging is done on update; it does not affect how files
are stored. See section Handling binary files, for more on
binary files.
The basic format of the file `cvswrappers' is:
wildcard [option value][option value]... where option is one of -m update methodology value: MERGE or COPY -k keyword expansion value: expansion mode and value is a single-quote delimited value.
For example, the following command imports a directory, treating files whose name ends in `.exe' as binary:
cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag
The `-i' flag in the `modules' file can be used to run a certain program whenever files are committed (see section The modules file). The files described in this section provide other, more flexible, ways to run programs whenever something is committed.
There are three kind of programs that can be run on commit. They are specified in files in the repository, as described below. The following table summarizes the file names and the purpose of the corresponding programs.
The administrative files such as `commitinfo', `loginfo', `rcsinfo', `verifymsg', etc., all have a common format. The purpose of the files are described later on. The common syntax is described here.
Each line contains the following:
Blank lines are ignored. Lines that start with the character `#' are treated as comments. Long lines unfortunately can not be broken in two parts in any way.
The first regular expression that matches the current directory name in the repository is used. The rest of the line is used as a file name or command-line as appropriate.
The `commitinfo' file defines programs to execute whenever `cvs commit' is about to execute. These programs are used for pre-commit checking to verify that the modified, added and removed files are really ready to be committed. This could be used, for instance, to verify that the changed files conform to to your site's standards for coding practice.
As mentioned earlier, each line in the `commitinfo' file consists of a regular expression and a command-line template. The template can include a program name and any number of arguments you wish to supply to it. The full path to the current source repository is appended to the template, followed by the file names of any files involved in the commit (added, removed, and modified files).
The first line with a regular expression matching the directory within the repository will be used. If the command returns a non-zero exit status the commit will be aborted.
If the repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.
All occurrences of the name `ALL' appearing as a regular expression are used in addition to the first matching regular expression or the name `DEFAULT'.
Note: when CVS is accessing a remote repository, `commitinfo' will be run on the remote (i.e., server) side, not the client side (see section Remote repositories).
Once you have entered a log message, you can evaluate that message to check for specific content, such as a bug ID. Use the `verifymsg' file to specify a program that is used to verify the log message. This program could be a simple script that checks that the entered message contains the required fields.
The `verifymsg' file is often most useful together with the `rcsinfo' file, which can be used to specify a log message template.
Each line in the `verifymsg' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.
One thing that should be noted is that the `ALL' keyword is not supported. If more than one matching line is found, the first one is used. This can be useful for specifying a default verification script in a directory, and then overriding it in a subdirectory.
If the repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.
If the verification script exits with a non-zero exit status, the commit is aborted.
Note that the verification script cannot change the log message; it can merely accept it or reject it.
The following is a little silly example of a `verifymsg' file, together with the corresponding `rcsinfo' file, the log message template and an verification script. We begin with the log message template. We want to always record a bug-id number on the first line of the log message. The rest of log message is free text. The following template is found in the file `/usr/cvssupport/tc.template'.
BugId:
The script `/usr/cvssupport/bugid.verify' is used to evaluate the log message.
#!/bin/sh
#
# bugid.verify filename
#
# Verify that the log message contains a valid bugid
# on the first line.
#
if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
exit 0
else
echo "No BugId found."
exit 1
fi
The `verifymsg' file contains this line:
^tc /usr/cvssupport/bugid.verify
The `rcsinfo' file contains this line:
^tc /usr/cvssupport/tc.template
NOTE: The `editinfo' feature has been
rendered obsolete. To set a default editor for log
messages use the EDITOR environment variable
(see section All environment variables which affect CVS) or the `-e' global
option (see section Global options). See section Verifying log messages,
for information on the use of the `verifymsg'
feature for evaluating log messages.
If you want to make sure that all log messages look the same way, you can use the `editinfo' file to specify a program that is used to edit the log message. This program could be a custom-made editor that always enforces a certain style of the log message, or maybe a simple shell script that calls an editor, and checks that the entered message contains the required fields.
If no matching line is found in the `editinfo'
file, the editor specified in the environment variable
$CVSEDITOR is used instead. If that variable is
not set, then the environment variable $EDITOR
is used instead. If that variable is not
set a default will be used. See section Committing your changes.
The `editinfo' file is often most useful together with the `rcsinfo' file, which can be used to specify a log message template.
Each line in the `editinfo' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.
One thing that should be noted is that the `ALL' keyword is not supported. If more than one matching line is found, the first one is used. This can be useful for specifying a default edit script in a module, and then overriding it in a subdirectory.
If the repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.
If the edit script exits with a non-zero exit status, the commit is aborted.
Note: when CVS is accessing a remote repository,
or when the `-m' or `-F' options to cvs
commit are used, `editinfo' will not be consulted.
There is no good workaround for this; use
`verifymsg' instead.
The following is a little silly example of a `editinfo' file, together with the corresponding `rcsinfo' file, the log message template and an editor script. We begin with the log message template. We want to always record a bug-id number on the first line of the log message. The rest of log message is free text. The following template is found in the file `/usr/cvssupport/tc.template'.
BugId:
The script `/usr/cvssupport/bugid.edit' is used to edit the log message.
#!/bin/sh
#
# bugid.edit filename
#
# Call $EDITOR on FILENAME, and verify that the
# resulting file contains a valid bugid on the first
# line.
if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
$CVSEDITOR $1
until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
do echo -n "No BugId found. Edit again? ([y]/n)"
read ans
case ${ans} in
n*) exit 1;;
esac
$CVSEDITOR $1
done
The `editinfo' file contains this line:
^tc /usr/cvssupport/bugid.edit
The `rcsinfo' file contains this line:
^tc /usr/cvssupport/tc.template
The `loginfo' file is used to control where
`cvs commit' log information is sent. The first
entry on a line is a regular expression which is tested
against the directory that the change is being made to,
relative to the $CVSROOT. If a match is found, then
the remainder of the line is a filter program that
should expect log information on its standard input.
If the repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.
All occurrences of the name `ALL' appearing as a regular expression are used in addition to the first matching regular expression or `DEFAULT'.
The first matching regular expression is used.
See section The commit support files, for a description of the syntax of the `loginfo' file.
The user may specify a format string as part of the filter. The string is composed of a `%' followed by a space, or followed by a single format character, or followed by a set of format characters surrounded by `{' and `}' as separators. The format characters are:
All other characters that appear in a format string expand to an empty field (commas separating fields are still provided).
For example, some valid format strings are `%', `%s', `%{s}', and `%{sVv}'.
The output will be a string of tokens separated by spaces. For backwards compatibility, the first token will be the repository subdirectory. The rest of the tokens will be comma-delimited lists of the information requested in the format string. For example, if `/u/src/master/yoyodyne/tc' is the repository, `%{sVv}' is the format string, and three files (ChangeLog, Makefile, foo.c) were modified, the output might be:
yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13
As another example, `%{}' means that only the name of the repository will be generated.
Note: when CVS is accessing a remote repository, `loginfo' will be run on the remote (i.e., server) side, not the client side (see section Remote repositories).
The following `loginfo' file, together with the tiny shell-script below, appends all log messages to the file `$CVSROOT/CVSROOT/commitlog', and any commits to the administrative files (inside the `CVSROOT' directory) are also logged in `/usr/adm/cvsroot-log'. Commits to the `prog1' directory are mailed to ceder.
ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER ^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log ^prog1 Mail -s %s ceder
The shell-script `/usr/local/bin/cvs-log' looks like this:
#!/bin/sh (echo "------------------------------------------------------"; echo -n $2" "; date; echo; cat) >> $1
It is often useful to maintain a directory tree which contains files which correspond to the latest version in the repository. For example, other developers might want to refer to the latest sources without having to check them out, or you might be maintaining a web site with CVS and want every checkin to cause the files used by the web server to be updated.
The way to do this is by having loginfo invoke
cvs update. Doing so in the naive way will
cause a problem with locks, so the cvs update
must be run in the background.
Here is an example for unix (this should all be on one line):
^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs; cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
This will cause checkins to repository directories
starting with cyclic-pages to update the checked
out tree in `/u/www/local-docs'.
The `rcsinfo' file can be used to specify a form to edit when filling out the commit log. The `rcsinfo' file has a syntax similar to the `verifymsg', `commitinfo' and `loginfo' files. See section The common syntax. Unlike the other files the second part is not a command-line template. Instead, the part after the regular expression should be a full pathname to a file containing the log message template.
If the repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.
All occurrences of the name `ALL' appearing as a regular expression are used in addition to the first matching regular expression or `DEFAULT'.
The log message template will be used as a default log message. If you specify a log message with `cvs commit -m message' or `cvs commit -f file' that log message will override the template.
See section Verifying log messages, for an example `rcsinfo' file.
When CVS is accessing a remote repository, the contents of `rcsinfo' at the time a directory is first checked out will specify a template which does not then change. If you edit `rcsinfo' or its templates, you may need to check out a new working directory.
There are certain file names that frequently occur inside your working copy, but that you don't want to put under CVS control. Examples are all the object files that you get while you compile your sources. Normally, when you run `cvs update', it prints a line for each file it encounters that it doesn't know about (see section update output).
CVS has a list of files (or sh(1) file name patterns)
that it should ignore while running update,
import and release.
This list is constructed in the following way.
RCS SCCS CVS CVS.adm
RCSLOG cvslog.*
tags TAGS
.make.state .nse_depinfo
*~ #* .#* ,* _$* *$
*.old *.bak *.BAK *.orig *.rej .del-*
*.a *.olb *.o *.obj *.so *.exe
*.Z *.elc *.ln
core
$CVSIGNORE is appended to the list.
In any of the 5 places listed above, a single exclamation mark (`!') clears the ignore list. This can be used if you want to store any file which normally is ignored by CVS.
Specifying `-I !' to cvs import will import
everything, which is generally what you want to do if
you are importing files from a pristine distribution or
any other source which is known to not contain any
extraneous files. However, looking at the rules above
you will see there is a fly in the ointment; if the
distribution contains any `.cvsignore' files, then
the patterns from those files will be processed even if
`-I !' is specified. The only workaround is to
remove the `.cvsignore' files in order to do the
import. Because this is awkward, in the future
`-I !' might be modified to override
`.cvsignore' files in each directory.
Note that the syntax of the ignore files consists of a series of lines, each of which contains a space separated list of filenames. This offers no clean way to specify filenames which contain spaces, but you can use a workaround like `foo?bar' to match a file named `foo bar' (it also matches `fooxbar' and the like). Also note that there is currently no way to specify comments.
It may be helpful to use CVS to maintain your own files in the `CVSROOT' directory. For example, suppose that you have a script `logcommit.pl' which you run by including the following line in the `commitinfo' administrative file:
ALL $CVSROOT/CVSROOT/logcommit.pl
To maintain `logcommit.pl' with CVS you would add the following line to the `checkoutlist' administrative file:
logcommit.pl
The format of `checkoutlist' is one line for each file that you want to maintain using CVS, giving the name of the file.
After setting up `checkoutlist' in this fashion, the files listed there will function just like CVS's built-in administrative files. For example, when checking in one of the files you should get a message such as:
cvs commit: Rebuilding administrative file database
and the checked out copy in the `CVSROOT' directory should be updated.
Note that listing `passwd' (see section Setting up the server for password authentication) in `checkoutlist' is not recommended for security reasons.
For information about keeping a checkout out copy in a more general context than the one provided by `checkoutlist', see section Keeping a checked out copy.
The file `$CVSROOT/CVSROOT/history' is used
to log information for the history command
(see section history--Show status of files and users). This file must be created to turn
on logging. This is done automatically if the
cvs init command is used to set up the
repository (see section Creating a repository).
The file format of the `history' file is
documented only in comments in the CVS source
code, but generally programs should use the cvs
history command to access it anyway, in case the
format changes with future releases of CVS.
Sometimes in writing an administrative file, you might want the file to be able to know various things based on environment CVS is running in. There are several mechanisms to do that.
To find the home directory of the user running CVS
(from the HOME environment variable), use
`~' followed by `/' or the end of the line.
Likewise for the home directory of user, use
`~user'. These variables are expanded on
the server machine, and don't get any reasonable
expansion if pserver (see section Direct connection with password authentication)
is in use; therefore user variables (see below) may be
a better choice to customize behavior based on the user
running CVS.
One may want to know about various pieces of
information internal to CVS. A CVS internal
variable has the syntax ${variable},
where variable starts with a letter and consists
of alphanumeric characters and `_'. If the
character following variable is a
non-alphanumeric character other than `_', the
`{' and `}' can be omitted. The CVS
internal variables are:
CVSROOT
RCSBIN
CVSEDITOR
VISUAL
EDITOR
USER
If you want to pass a value to the administrative files
which the user who is running CVS can specify,
use a user variable.
To expand a user variable, the
administrative file contains
${=variable}. To set a user variable,
specify the global option `-s' to CVS, with
argument variable=value. It may be
particularly useful to specify this option via
`.cvsrc' (see section Default options and the ~/.cvsrc file).
For example, if you want the administrative file to
refer to a test directory you might create a user
variable TESTDIR. Then if CVS is invoked
as
cvs -s TESTDIR=/work/local/tests
and the
administrative file contains sh
${=TESTDIR}/runtests, then that string is expanded
to sh /work/local/tests/runtests.
All other strings containing `$' are reserved; there is no way to quote a `$' character so that `$' represents itself.
The administrative file `config' contains various miscellaneous settings which affect the behavior of CVS. The syntax is slightly different from the other administrative files. Variables are not expanded. Lines which start with `#' are considered comments. Other lines consist of a keyword, `=', and a value. Note that this syntax is very strict. Extraneous spaces or tabs are not permitted.
Currently defined keywords are:
RCSBIN=bindir
SystemAuth=value
PreservePermissions=value
TopLevelAdmin=value
CVSROOT for
each command. It also provides a place for the
`CVS/Template' file (see section How data is stored in the working directory).
LockDir=directory
Go to the first, previous, next, last section, table of contents.