[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 2.4 The administrative files.
The most important of these files is the `modules' file, which defines the modules inside the repository.
C.1 The modules file | Defining modules | |
C.2 The cvswrappers file | Specify binary-ness based on file name | |
C.3 The commit support files | The commit support files (commitinfo, verifymsg, loginfo) | |
C.5 Taginfo | Verifying/Logging tags | |
C.4 Rcsinfo | Templates for the log messages | |
C.6 Ignoring files via cvsignore | ||
C.7 The checkoutlist file | Adding your own administrative files | |
C.8 The history file | History information | |
C.9 Expansions in administrative files | Various variables are expanded | |
C.10 The CVSROOT/config configuration file | Miscellaneous CVS configuration |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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'.
C.1.1 Alias modules | The simplest kind of module | |
C.1.2 Regular modules | ||
C.1.3 Ampersand modules | ||
C.1.4 Excluding directories | Excluding directories from a module | |
C.1.5 Module options | Regular and ampersand modules can take options | |
C.1.6 How the modules file "program options" programs are run | How the modules "program options" programs are run. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 $ |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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'.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Either regular modules or ampersand modules can contain options, which supply additional information concerning the module.
-d name
-e 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 the `taginfo' file is a better solution (see section C.5 Taginfo).
You should also see see section C.1.6 How the modules file "program options" programs are run about how the "program options" programs are run.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 file system, 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 9. 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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The `-i' flag in the `modules' file can be used to run a certain program whenever files are committed (see section C.1 The modules file). The files described in this section provide other, more flexible, ways to run programs whenever something is committed.
There are three kinds 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.
C.3.1 The common syntax | ||
C.3.3 Commitinfo | Pre-commit checking | |
C.3.4 Verifying log messages | How are log messages evaluated? | |
C.3.5 Loginfo | Where should log messages be sent? | |
C.3.2 Updating legacy repositories to stop using deprecated command line template formats |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
Note: The following information on format strings is valid
as long as the line UseNewInfoFmtStrings=yes
appears in
your repository's config file (see section C.10 The CVSROOT/config configuration file). Otherwise,
default format strings may be appended to the command line and
the `loginfo' file, especially, can exhibit slightly
different behavior. For more information,
See section C.3.2 Updating legacy repositories to stop using deprecated command line template formats.
In the cases where the second segment of the matched line is a command line template (e.g. `commitinfo', `loginfo', & `verifymsg'), the command line template may contain format strings which will be replaced with specific values before the script is run.
Format strings can represent a single variable or one or more attributes of a list variable. An example of a list variable would be the list available to scripts hung on the loginfo hooks - the list of files which were just committed. In the case of loginfo, three attributes are available for each list item: file name, precommit version, and postcommit version.
Format strings consist of a `%' character followed by an optional `{' (required in the multiple list attribute case), a single format character representing a variable or a single attribute of list elements or multiple format characters representing attributes of list elements, and a closing `}' when the open bracket was present.
Flat format strings (single format characters which get replaced with a single value) will generate a single argument to the called script, regardless of whether the replacement variable contains white space or other special characters.
List attributes will generate an argument for each attribute requested for each list item. For example, `%{sVv}' in a `loginfo' command template will generate three arguments (file name, precommit version, postcommit version, ...) for each file committed. As in the flat format string case, each attribute will be passed in as a single argument regardless of whether it contains white space or other special characters. `%%' will be replaced with a literal `%'.
The format strings available to all script hooks are:
$CVSROOT
)
Other format strings are file specific. See the docs on the particular administration files for more information (see section C. Reference manual for Administrative files).
As an example, the following line in a `loginfo' file would match only the directory `module' and any subdirectories of `module':
^module\(/\|$\) (echo; echo %p; echo %{sVv}; cat) >>$CVSROOT/CVSROOT/commitlog |
Using this same line and assuming a commit of new revisions 1.5.4.4 and 1.27.4.1 based on old revisions 1.5.4.3 and 1.27, respectively, of file1 and file2 in module, something like the following log message should be appended to commitlog:
module file1 1.5.4.3 1.5.4.4 file2 1.27 1.27.4.1 Update of /cvsroot/module In directory localhost.localdomain:/home/jrandom/work/module Modified Files: file1 file2 Log Message: A log message. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If you are attempting to maintain a legacy repository which was making use of the `commitinfo', `editinfo', `verifymsg', `loginfo', and/or `taginfo' script hooks, you should have no immediate problems with using the current CVS executable, but your users will probably start to see deprecation warnings.
The reason for this is that all of the script hooks have been updated to use a new command line parser that extensibly supports multiple `loginfo' & `notify' style format strings (see section C.3.1 The common syntax) and this support is not completely compatible with the old style format strings.
The quick upgrade method is to stick a `1' after each format string in your old `loginfo' file. For example:
DEFAULT (echo ""; id; echo %{sVv}; date; cat) >> $CVSROOT/CVSROOT/commitlog |
would become:
DEFAULT (echo ""; id; echo %1{sVv}; date; cat) >> $CVSROOT/CVSROOT/commitlog |
If you were counting on the fact that only the first `%' in the line was replaced as a format string, you may also have to double up any further percent signs on the line.
If you did this all at once and checked it in, everything should still be running properly.
Now add the following line to your config file (see section C.10 The CVSROOT/config configuration file):
UseNewInfoFmtStrings=yes |
Everything should still be running properly, but your users will probably start seeing new deprecation warnings. Dealing with the deprecation warnings now generated by `commitinfo', `editinfo', `verifymsg', and `taginfo' should be easy. Simply specify what are currently implicit arguments explicitly. This means appending the following strings to each active command line template in each file:
commitinfo
editinfo
taginfo
verifymsg
If you don't desire that any of the newly available information be passed to the scripts hanging off of these hooks, no further modifications to these files should be necessary to insure current and future compatibility with CVS's format strings.
Fixing `loginfo' could be a little tougher. The old style `loginfo' format strings caused a single space and comma separated argument to be passed in in place of the format string. This is what will continue to be generated due to the deprecated `1' you inserted into the format strings.
Since the new format separates each individual item and passes it into the script as a separate argument (for a good reason - arguments containing commas and/or white space are now parsable), to remove the deprecated `1' from your `loginfo' command line templates, you will most likely have to rewrite any scripts called by the hook to handle the new argument format.
Also note that the way `%' followed by unrecognized characters and by `{}' was treated in past versions of CVS is not strictly adhered to as there were bugs in the old versions. Specifically, `%{}' would eat the next character and unrecognized strings resolved only to the empty string, which was counter to what was stated in the documentation. This version will do what the documentation said it should have (if you were using only some combination of `%{sVv}', e.g. `%{sVv}', `%{sV}', or `%v', you should have no troubles).
On the bright side, you should have plenty of time to do this before all support for the old format strings is removed from CVS, so you can just put up with the deprecation warnings for awhile if you like.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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, as well as format strings. For more info, see section C.3.1 The common syntax.
In addition to the common format strings (see section C.3.1 The common syntax), `commitinfo' supports:
Currently, if no format strings are specified, a default string of ` %r/%p %{s}' will be appended to the command line template before replacement is performed, but this feature is deprecated. It is simply in place so that legacy repositories will remain compatible with the new CVS application. For information on updating, see section C.3.2 Updating legacy repositories to stop using deprecated command line template formats.
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'.
The command will be run in the root of the workspace containing the new versions of any files the user would like to modify (commit), or in a copy of the workspace on the server (see section 2.9 Remote repositories). If a file is being removed, there will be no copy of the file under the current directory. If a file is being added, there will be no corresponding archive file in the repository unless the file is being resurrected.
Note that both the repository directory and the corresponding Attic (see section 2.2.4 The attic) directory may need to be checked to locate the archive file corresponding to any given file being committed. Much of the information about the specific commit request being made, including the destination branch, commit message, and command line options specified, is not available to the command.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
In addition to the common format strings (see section C.3.1 The common syntax), `verifymsg' supports:
Currently, if no format strings are specified, a default string of ` %l' will be appended to the command line template before replacement is performed, but this feature is deprecated. It is simply in place so that legacy repositories will remain compatible with the new CVS application. For information on updating, see section C.3.2 Updating legacy repositories to stop using deprecated command line template formats.
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.
In the default configuration, CVS allows the verification script to change the log message. This is controlled via the RereadLogAfterVerify CVSROOT/config option.
When `RereadLogAfterVerify=always' or `RereadLogAfterVerify=stat', the log message will either always be reread after the verification script is run or reread only if the log message file status has changed.
See section C.10 The CVSROOT/config configuration file, for more on CVSROOT/config options.
It is NOT a good idea for a `verifymsg' script to
interact directly with the user in the various
client/server methods. For the pserver
method,
there is no protocol support for communicating between
`verifymsg' and the client on the remote end. For the
ext
and server
methods, it is possible
for CVS to become confused by the characters going
along the same channel as the CVS protocol
messages. See 2.9 Remote repositories, for more
information on client/server setups. In addition, at the time
the `verifymsg' script runs, the CVS
server has locks in place in the repository. If control is
returned to the user here then other users may be stuck waiting
for access to the repository.
This option can be useful if you find yourself using an rcstemplate that needs to be modified to remove empty elements or to fill in default values. It can also be useful if the rcstemplate has changed in the repository and the CVS/Template was not updated, but is able to be adapted to the new format by the verification script that is run by `verifymsg'.
An example of an update might be to change all occurrences of 'BugId:' to be 'DefectId:' (which can be useful if the rcstemplate has recently been changed and there are still checked-out user trees with cached copies in the CVS/Template file of the older version).
Another example of an update might be to delete a line that contains 'BugID: none' from the log message after validation of that value as being allowed is made.
C.3.4.1 Verifying log messages | Verifymsg example |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then exit 0 elif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then # It is okay to allow commits with 'BugId: none', # but do not put that text into the real log message. grep -v '^BugId:[ ]*none$' > $1.rewrite mv $1.rewrite $1 exit 0 else echo "No BugId found." exit 1 fi |
The `verifymsg' file contains this line:
^tc /usr/cvssupport/bugid.verify %l |
The `rcsinfo' file contains this line:
^tc /usr/cvssupport/tc.template |
The `config' file contains this line:
RereadLogAfterVerify=always |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The `loginfo' file is used to control where `cvs commit' log information is sent. See section C.5 Taginfo, for how to log tagging information.
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.
Note that the filter program must read all
of the log information or CVS may fail with a broken pipe signal.
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.
In addition to the common format strings (see section C.3.1 The common syntax), `loginfo' supports:
For example, some valid format strings are `%%', `%s', `%{s}', and `%{sVv}'.
Currently, if `UseNewInfoFmtStrings' is not set in the `config' administration file (see section C.10 The CVSROOT/config configuration file), the format strings will be substituted as they were in past versions of CVS, but this feature is deprecated. It is simply in place so that legacy repositories will remain compatible with the new CVS application. For information on updating, please see C.3.2 Updating legacy repositories to stop using deprecated command line template formats.
See section C.3 The commit support files, for a description of the syntax of the `loginfo' file.
As an example, if `/u/src/master/yoyodyne/tc' is the repository, `%p' and `%{sVv}' are the format strings, 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 |
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 2.9 Remote repositories).
C.3.5.1 Loginfo example | ||
C.3.5.2 Keeping a checked out copy | Updating a tree on every checkin |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 $USER ^prog1\(/\|$\) Mail -s "%p %s" ceder |
The shell-script `/usr/local/bin/cvs-log' looks like this:
#!/bin/sh (echo "------------------------------------------------------"; echo -n "$2 "; date; echo; cat) >> $1 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 directory cyclic-pages
and its subdirectories to update the checked
out tree in `/u/www/local-docs'.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 C.3.1 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 C.3.4 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. This template will be updated on all `cvs update' commands. It will also be added to new directories added with a `cvs add new-directory' command. In versions of CVS prior to version 1.12, the `CVS/Template' file was not updated. If the CVS server is at version 1.12 or higher an older client may be used and the `CVS/Template' will be updated from the server.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
tag
or rtag
command. The `taginfo' file has the standard form
for administrative files (see section C. Reference manual for Administrative files), where each line is a regular expression
followed by a command to execute.
In addition to the common format strings (see section C.3.1 The common syntax), `taginfo' supports:
T
for branch, N
for not-branch, or ?
for
unknown, as during delete operations)
add
for tag
, mov
for tag -F
, or
del
for tag -d
)
For example, some valid format strings are `%%', `%p', `%t', `%s', `%{s}', and `%{sVv}'.
Currently, if no format strings are specified, a default string of ` %t %o %p %{sv}' will be appended to the command line template before replacement is performed, but this feature is deprecated. It is simply in place so that legacy repositories will remain compatible with the new CVS application. For information on updating, see section C.3.2 Updating legacy repositories to stop using deprecated command line template formats.
A non-zero exit of the filter program will cause the tag to be aborted.
Here is an example of using `taginfo' to log tag
and rtag
commands. In the `taginfo' file put:
ALL /usr/local/cvsroot/CVSROOT/loggit %t %b %o %p %{sVv} |
Where `/usr/local/cvsroot/CVSROOT/loggit' contains the following script:
#!/bin/sh echo "$@" >>/home/kingdon/cvsroot/CVSROOT/taglog |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 A.18.2 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 %r/%p %s |
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, followed optionally by more whitespace and any error message that should print if the file cannot be checked out into CVSROOT after a commit:
logcommit.pl Could not update CVSROOT/logcommit.pl. |
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 2.9.3.1 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 C.3.5.2 Keeping a checked out copy.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The file `$CVSROOT/CVSROOT/history' is used
to log information for the history
command
(see section A.12 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 2.6 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 2.9.3 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
EDITOR
VISUAL
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 A.3 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.
Environment variables passed to administrative files are:
CVS_USER
CVS_USER
and USER
may differ when `$CVSROOT/CVSROOT/passwd'
is used to map CVS usernames to system usernames.)
LOGNAME
USER
LOGNAME
.
Do not confuse this with the internal variable of the same name.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
TopLevelAdmin=value
This option is useful if you find yourself performing
many commands at the top level of your working
directory, rather than in one of the checked out
subdirectories. The `CVS' directory created there
will mean you don't have to specify CVSROOT
for
each command. It also provides a place for the
`CVS/Template' file (see section 2.3 How data is stored in the working directory).
LockDir=directory
Before enabling the LockDir option, make sure that you have tracked down and removed any copies of CVS 1.9 or older. Such versions neither support LockDir, nor will give an error indicating that they don't support it. The result, if this is allowed to happen, is that some CVS users will put the locks one place, and others will put them another place, and therefore the repository could become corrupted. CVS 1.10 does not support LockDir but it will print a warning if run on a repository with LockDir enabled.
LogHistory=value
RereadLogAfterVerify=value
Note: the `stat' mode can cause CVS to pause for up to one extra second per directory committed. This can be less IO and CPU intensive but is not recommended for use with large repositories
See section C.3.4 Verifying log messages, for more information on how verifymsg may be used.
UserAdminOptions=value
cvs admin
command (see section A.6 admin--Administration) for users not in the cvsadmin
group.
The value string is a list of single character options
which should be allowed. If a user who is not a member of the
cvsadmin
group tries to execute any cvs admin
option which is not listed they will will receive an error message
reporting that the option is restricted.
If no cvsadmin
group exists on the server, CVS will
ignore the UserAdminOptions
keyword (see section A.6 admin--Administration).
When not specified, UserAdminOptions
defaults to
`k'. In other words, it defaults to allowing
users outside of the cvsadmin
group to use the
cvs admin
command only to change the default keyword
expansion mode for files.
As an example, to restrict users not in the cvsadmin
group to using cvs admin
to change the default keyword
substitution mode, lock revisions, unlock revisions, and
replace the log message, use `UserAdminOptions=klum'.
UseNewInfoFmtStrings=value
Note that new repositories (created with the cvs init
command)
will have this value set to `yes', but the default value is `no'.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |