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.
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.m4With 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
-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
. There is no way to
specify a program to run when tag
is executed.
-u prog
Wrappers allow you to set a hook which transforms files on their way in and out of CVS. Most or all of the wrappers features do not work with client/server CVS.
The file `cvswrappers' defines the script that will be
run on a file when its name matches a regular
expresion. There are two scripts that can be run on a
file or directory. One script is executed on the file/directory
before being checked into the repository (this is denoted
with the -t
flag) and the other when the file is
checked out of the repository (this is denoted with the
-f
flag)
The `cvswrappers' also has a `-m' option to
specify the merge methodology that should be used when
the file is updated. MERGE
means the usual
CVS behavior: try to merge the files (this
generally will not work for binary files). COPY
means that cvs update
will merely copy one
version over the other, and require the user using
mechanisms outside CVS, to insert any necessary
changes.
The `-m' wrapper option only affects behavior when
merging is done on update; it does not affect how files
are stored. See 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 -f from cvs filter value: path to filter -t to cvs filter value: path to filter -m update methodology value: MERGE or COPY -k keyword expansion value: expansion mode and value is a single-quote delimited value.
*.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY' *.c -t 'indent %s %s'
The above example of a `cvswrappers' file
states that all files/directories that end with a .nib
should be filtered with the `wrap' program before
checking the file into the repository. The file should
be filtered though the `unwrap' program when the
file is checked out of the repository. The
`cvswrappers' file also states that a COPY
methodology should be used when updating the files in
the repository (that is no merging should be performed).
The last example line says that all files that end with
a *.c
should be filtered with `indent'
before being checked into the repository. Unlike the previous
example no filtering of the *.c
file is done when
it is checked out of the repository.
The -t
filter is called with two arguments,
the first is the name of the file/directory to filter
and the second is the pathname to where the resulting
filtered file should be placed.
The -f
filter is called with one argument,
which is the name of the file to filter from. The end
result of this filter will be a file in the users directory
that they can work on as they normally would.
For another 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 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.
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 relative path to the module 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 occurances 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).
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 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 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.
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.
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.
All occurances 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.
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'.
ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog ^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
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 (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 `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.
All occurances 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 Editinfo example, 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.
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 resonable
expansion if pserver (see section Direct connection with password authentication)
is in used; 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 alphanumberic 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 that 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.
Go to the first, previous, next, last section, table of contents.