Go to the previous, next section.
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.
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 create a file with the right format in `$CVSROOT/CVSROOT/modules,v'. The mkmodules(1) command should be run whenever the modules file changes, so that the appropriate files can be generated (depending on how you have configured CVS operation).
To allow convenient editing of the `modules' file itself, the file should include an entry like the following (where localbin represents the directory where your site installs programs like mkmodules(1)):
modules -i /localbin/mkmodules CVSROOT modules
This defines the name `modules' as the module name for the file itself, so that you can use
$ cvs checkout modules
to get a copy of the file that you can edit. You should define similar module entries for the other configuration files described in this appendix, except `history').
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.
A module definition is a single line of the `modules' file, in either of two formats. In both cases, mname represents the symbolic module name, and the remainder of the line is its definition.
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.
mname [ options ] dir [ files... ] [ &module... ]
$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.
By explicitly specifying files in the module definition after dir, you can select particular files from directory dir. The sample definition for `modules' is an example of a module defined with a single file from a particular directory. Here is another example:
m4test unsupported/gnu/m4 foreach.m4 forloop.m4
With this definition, executing `cvs checkout m4test' will create a single working directory `m4test' containing the two files listed, which both come from a common directory several levels deep in the CVS source repository.
A module definition can refer to other modules by
including `&module' in its definition.
checkout creates a subdirectory for each such
module, in your working directory.
-d name
-i prog
-o prog
-s status
-t prog
rtag. prog runs
with two arguments: the module name and the symbolic
tag specified to rtag. There is no way to
specify a program to run when tag is executed.
-u prog
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 four files `commitinfo', `loginfo', `rcsinfo' and `editinfo' 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.
Whenever one of the regular expressions matches a directory name in the repository, the rest of the line is used.
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).
All lines with a regular expression matching the relative path to the module will be used. If any of the commands return 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.
If the name `ALL' appears as a regular expression it is always used in addition to any matching regular expression or `DEFAULT'.
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
$EDITOR is used instead. If that variable is not
set a precompiled default, normally vi, will be
used.
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 last 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 edit script exits with a non-zero exit status, the commit is aborted.
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.
$EDITOR $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
$EDITOR $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.
The filter program may use one and only one % modifier (a la printf). If `%s' is specified in the filter program, a brief title is included (enclosed in single quotes) showing the modified file names.
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 name `ALL' appears as a regular expression it is always used in addition to any matching regular expression or `DEFAULT'.
All matching regular expressions are used.
See section The commit support files, for a description of the syntax of the `loginfo' file.
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' and mailed to ceder.
ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog ^CVSROOT Mail -s %s ceder ^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log
The shell-script `/usr/local/bin/cvs-log' looks like this:
#!/bin/sh
(echo "-----------------------------------------------------------------";
echo -n $USER" ";
date;
echo;
sed '1s+'${CVSROOT}'++') >> $1
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 `editinfo', `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.
If the name `ALL' appears as a regular expression it is always 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 Editinfo example, for an example `rcsinfo' file.
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.
RCSLOG RCS SCCS
CVS* cvslog.*
tags TAGS
.make.state .nse_depinfo
*~ #* .#* ,*
*.old *.bak *.BAK *.orig *.rej .del-*
*.a *.o *.so *.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.
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
cvsinit script is used to set up the repository.
The file format of the `history' file is unfortunately not yet documented anywhere, but it is fairly easy to understand most of it.
When you install CVS for the first time, you should follow the instructions in the `INSTALL' file to set up the repository.
If you want to set up another repository, the easiest
way to get a reasonable set of working administrative
files is to get the source to CVS, and run the
cvsinit shell script. It will set up an empty
repository in the directory defined by the environment
variable $CVSROOT. (cvsinit is careful to
never overwrite any existing files in the repository,
so no harm is done if you run cvsinit on
an already set-up repository.)
Go to the previous, next section.