This is cvs.info, produced by makeinfo version 4.3 from
../../doc/cvs.texinfo.

INFO-DIR-SECTION GNU Packages
START-INFO-DIR-ENTRY
* CVS: (cvs).                   Concurrent Versions System
END-INFO-DIR-ENTRY
INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* cvs: (cvs)CVS commands.       Concurrent Versions System
END-INFO-DIR-ENTRY


File: cvs.info,  Node: Trigger Script Security,  Next: commit files,  Prev: syntax,  Up: Trigger Scripts

Security and the Trigger Scripts
--------------------------------

   Security is a huge subject, and implementing a secure system is a
non-trivial task.  This section will barely touch on all the issues
involved, but it is well to note that, as with any script you will be
allowing an untrusted user to run on your server, there are measures
you can take to help prevent your trigger scripts from being abused.

   For instance, since the CVS trigger scripts all run in a copy of the
user's sandbox on the server, a naively coded Perl trigger script which
attempts to use a Perl module that is not installed on the system can
be hijacked by any user with commit access who is checking in a file
with the correct name.  Other scripting languages may be vulnerable to
similar hacks.

   One way to make a script more secure, at least with Perl, is to use
scripts which invoke the `-T', or "taint-check" switch on their `#!'
line.  In the most basic terms, this causes Perl to avoid running code
that may have come from an external source.  Please run the `perldoc
perlsec' command for more on Perl security.  Again, other languages may
implement other security verification hooks which look more or less
like Perl's "taint-check" mechanism.


File: cvs.info,  Node: commit files,  Next: commitinfo,  Prev: Trigger Script Security,  Up: Trigger Scripts

The commit support files
------------------------

   The `-i' flag in the `modules' file can be used to run a certain
program whenever files are committed (*note modules::).  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.

`commitinfo'
     The program is responsible for checking that the commit is
     allowed.  If it exits with a non-zero exit status the commit will
     be aborted.  *Note commitinfo::.

`verifymsg'
     The specified program is used to evaluate the log message, and
     possibly verify that it contains all required fields.  This is
     most useful in combination with the `rcsinfo' file, which can hold
     a log message template (*note rcsinfo::).  *Note verifymsg::.

`loginfo'
     The specified program is called when the commit is complete.  It
     receives the log message and some additional information and can
     store the log message in a file, or mail it to appropriate
     persons, or maybe post it to a local newsgroup, or...  Your
     imagination is the limit!  *Note loginfo::.

* Menu:

* Updating Commit Files::       Updating legacy repositories to stop using
                                deprecated command line template formats


File: cvs.info,  Node: Updating Commit Files,  Up: commit files

Updating legacy repositories to stop using deprecated command line template formats
...................................................................................

   New repositories are created set to use the new format strings by
default, so if you are creating a new repository, you shouldn't have to
worry about this section.

   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 (*note 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 (*note config::):
     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'
     ` %r/%p %s'

`editinfo'
     ` %l'

`taginfo'
     ` %t %o %p %{sv}'

`verifymsg'
     ` %l'

   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.


File: cvs.info,  Node: commitinfo,  Next: verifymsg,  Prev: commit files,  Up: Trigger Scripts

Commitinfo
----------

   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.

   The `commitinfo' file has the standard form for script hooks (*note
Trigger Scripts::), where each line is a regular expression followed by
a command to execute.  It supports only the DEFAULT keywords.

   In addition to the common format strings (*note syntax::),
`commitinfo' supports:

{s}
     a list of the names of files to be committed

   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, *note Updating
Commit 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.

   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 (*note 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
(*note 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.


File: cvs.info,  Node: verifymsg,  Next: loginfo,  Prev: commitinfo,  Up: Trigger Scripts

Verifying log messages
----------------------

   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
(*note rcsinfo::).

   The `verifymsg' file has the standard form for script hooks (*note
Trigger Scripts::), where each line is a regular expression followed by
a command to execute.  It supports only the DEFAULT keywords.

   In addition to the common format strings (*note syntax::),
`verifymsg' supports:

l
     the full path to the file containing the log message to be verified

{sV}
     File attributes, where:
    s
          file name

    V
          old version number (pre-checkin)

   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, *note Updating Commit
Files::.

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

   *Note config::, 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 *Note 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.

* Menu:

* verifymsg example::            Verifymsg example


File: cvs.info,  Node: verifymsg example,  Up: verifymsg

Verifying log messages
......................

   The following is a little silly example of a `verifymsg' file,
together with the corresponding `rcsinfo' file, the log message
template and a 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 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


File: cvs.info,  Node: loginfo,  Next: postadmin,  Prev: verifymsg,  Up: Trigger Scripts

Loginfo
-------

   The `loginfo' file is used to control where log information is sent
after versioned changes are made to repository archive files and after
directories are added ot the repository.  *Note posttag:: for how to
log tagging information and *Note postadmin:: for how to log changes
due to the `admin' command.

   The `loginfo' file has the standard form for script hooks (*note
Trigger Scripts::), where each line is a regular expression followed by
a command to execute.  It supports the ALL and DEFAULT keywords.

   Any specified scripts are called:

`commit'
     Once per directory, immediately after a successfully completing
     the commit of all files within that directory.

`import'
     Once per import, immediately after completion of all write
     operations.

`add'
     Immediately after the successful `add' of a directory.

   Any script called via `loginfo' will be fed the log information on
its standard input.  Note that the filter program *must* read *all* of
the log information from its standard input or CVS may fail with a
broken pipe signal.

   In addition to the common format strings (*note syntax::), `loginfo'
supports:

{stVv}
     File attributes, where:
    s
          file name

    T
          tag name of destination, or the empty string when there is no
          associated tag name (this usually means the trunk)

    V
          old version number (pre-checkin)

    v
          new version number (post-checkin)

   For example, some valid format strings are `%%', `%s', `%{s}', and
`%{stVv}'.

   Currently, if `UseNewInfoFmtStrings' is not set in the `config'
administration file (*note config::), 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 *Note Updating Commit Files::.

   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 (*note
Remote repositories::).

* Menu:

* loginfo example::                          Loginfo example
* Keeping a checked out copy::               Updating a tree on every checkin


File: cvs.info,  Node: loginfo example,  Next: Keeping a checked out copy,  Up: loginfo

Loginfo example
...............

   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


File: cvs.info,  Node: Keeping a checked out copy,  Prev: loginfo example,  Up: loginfo

Keeping a checked out copy
..........................

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


File: cvs.info,  Node: postadmin,  Next: taginfo,  Prev: loginfo,  Up: Trigger Scripts

Logging admin commands
----------------------

   The `postadmin' file defines programs to execute after an `admin'
command modifies files.  The `postadmin' file has the standard form for
script hooks (*note Trigger Scripts::), where each line is a regular
expression followed by a command to execute.  It supports the ALL and
DEFAULT keywords.

   The `postadmin' file supports no format strings other than the common
ones (*note syntax::),


File: cvs.info,  Node: taginfo,  Next: posttag,  Prev: postadmin,  Up: Trigger Scripts

Taginfo
-------

   The `taginfo' file defines programs to execute when someone executes
a `tag' or `rtag' command.  The `taginfo' file has the standard form
for script hooks (*note Trigger Scripts::), where each line is a
regular expression followed by a command to execute.  It supports the
ALL and DEFAULT keywords.

   In addition to the common format strings (*note syntax::), `taginfo'
supports:

b
     tag type (`T' for branch, `N' for not-branch, or `?' for unknown,
     as during delete operations)

o
     operation (`add' for `tag', `mov' for `tag -F', or `del' for `tag
     -d')

t
     new tag name

{sTVv}
     file attributes, where:
    s
          file name

    T
          tag name of destination, or the empty string when there is no
          associated tag name (this usually means the trunk)

    V
          old version number (for a move or delete operation)

    v
          new version number (for an add or move operation)

   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, *note Updating
Commit Files::.

   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


File: cvs.info,  Node: posttag,  Next: postwatch,  Prev: taginfo,  Up: Trigger Scripts

Logging tags
------------

   The `posttag' file defines programs to execute after a `tag' or
`rtag' command modifies files.  The `posttag' file has the standard
form for script hooks (*note Trigger Scripts::), where each line is a
regular expression followed by a command to execute.  It supports the
ALL and DEFAULT keywords.

   The `posttag' admin file supports the same format strings as the
`taginfo' file (*note taginfo::),


File: cvs.info,  Node: postwatch,  Next: preproxy,  Prev: posttag,  Up: Trigger Scripts

Logging watch commands
----------------------

   The `postwatch' file defines programs to execute after any command
(for instance, `watch', `edit', `unedit', or `commit') modifies any
`CVS/fileattr' file in the repository (*note Watches::).  The
`postwatch' file has the standard form for script hooks (*note Trigger
Scripts::), where each line is a regular expression followed by a
command to execute.  It supports the ALL and DEFAULT keywords.

   The `postwatch' file supports no format strings other than the common
ones (*note syntax::), but it is worth noting that the `%c' format
string may not be replaced as you might expect.  Client runs of `edit'
and `unedit' can sometimes skip contacting the CVS server and cache the
notification of the file attribute change to be sent the next time the
client contacts the server for whatever other reason,


File: cvs.info,  Node: preproxy,  Next: postproxy,  Prev: postwatch,  Up: Trigger Scripts

Launch a Script before Proxying
-------------------------------

   The `preproxy' file defines programs to execute after a secondary
server receives a write request from a client, just before it starts up
the primary server and becomes a write proxy.  This hook could be used
to dial a modem, launch an SSH tunnel, establish a VPN, or anything
else that might be necessary to do before contacting the primary server.

   `preproxy' scripts are called once, at the time of the write
request, with the repository argument (if requested) set from the
topmost directory sent by the client.

   The `preproxy' file has the standard form for script hooks (*note
Trigger Scripts::), where each line is a regular expression followed by
a command to execute.  It supports the ALL and DEFAULT keywords.

   In addition to the common format strings, the `preproxy' file
supports the following format string:

P
     the CVSROOT string which specifies the primary server


File: cvs.info,  Node: postproxy,  Prev: preproxy,  Up: Trigger Scripts

Launch a Script after Proxying
------------------------------

   The `postproxy' file defines programs to execute after a secondary
server notes that the connection to the primary server has shut down
and before it releases the client by shutting down the connection to
the client.  This could hook could be used to disconnect a modem, an
SSH tunnel, a VPN, or anything else that might be necessary to do after
contacting the primary server.  This hook should also be used to pull
updates from the primary server before allowing the client which did
the write to disconnect since otherwise the client's next read request
may generate error messages and fail upon encountering an out of date
repository on the secondary server.

   `postproxy' scripts are called once per directory.

   The `postproxy' file has the standard form for script hooks (*note
Trigger Scripts::), where each line is a regular expression followed by
a command to execute.  It supports the ALL and DEFAULT keywords.

   In addition to the common format strings, the `postproxy' file
supports the following format string:

P
     the CVSROOT string which specifies the primary server


File: cvs.info,  Node: rcsinfo,  Next: cvsignore,  Prev: Trigger Scripts,  Up: Administrative files

Rcsinfo
=======

   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.  *Note 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.

   *Note verifymsg::, 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.


File: cvs.info,  Node: cvsignore,  Next: checkoutlist,  Prev: rcsinfo,  Up: Administrative files

Ignoring files via cvsignore
============================

   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 (*note 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.

   * The list is initialized to include certain file name patterns:
     names associated with CVS administration, or with other common
     source control systems; common names for patch files, object files,
     archive files, and editor backup files; and other names that are
     usually artifacts of assorted utilities.  Currently, the default
     list of ignored file name patterns is:

              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

   * The per-repository list in `$CVSROOT/CVSROOT/cvsignore' is
     appended to the list, if that file exists.

   * The per-user list in `.cvsignore' in your home directory is
     appended to the list, if it exists.

   * Any entries in the environment variable `$CVSIGNORE' is appended
     to the list.

   * Any `-I' options given to CVS is appended.

   * As CVS traverses through your directories, the contents of any
     `.cvsignore' will be appended to the list.  The patterns found in
     `.cvsignore' are only valid for the directory that contains them,
     not for any sub-directories.

   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.


File: cvs.info,  Node: checkoutlist,  Next: history file,  Prev: cvsignore,  Up: Administrative files

The checkoutlist file
=====================

   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' (*note Password authentication server::)
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 *Note Keeping a
checked out copy::.


File: cvs.info,  Node: history file,  Next: Variables,  Prev: checkoutlist,  Up: Administrative files

The history file
================

   By default, the file `$CVSROOT/CVSROOT/history' is used to log
information for the `history' command (*note history::).  This file
name may be changed with the `HistoryLogPath' and `HistorySearchPath'
config options (*note config::).

   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.


File: cvs.info,  Node: Variables,  Next: config,  Prev: history file,  Up: Administrative files

Expansions in administrative files
==================================

   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 (*note Password authenticated::) 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'
     This is the absolute path to the current CVS root directory.
     *Note Repository::, for a description of the various ways to
     specify this, but note that the internal variable contains just
     the directory and not any of the access method information.

`RCSBIN'
     In CVS 1.9.18 and older, this specified the directory where CVS
     was looking for RCS programs.  Because CVS no longer runs RCS
     programs, specifying this internal variable is now an error.

`CVSEDITOR'
`EDITOR'
`VISUAL'
     These all expand to the same value, which is the editor that CVS
     is using.  *Note Global options::, for how to specify this.

`USER'
     Username of the user running CVS (on the CVS server machine).
     When using pserver, this is the user specified in the repository
     specification which need not be the same as the username the
     server is running as (*note Password authentication server::).  Do
     not confuse this with the environment variable of the same name.

`SESSIONID'
     Unique Session ID of the CVS process. This is a random string of
     printable characters of at least 16 characters length. Users
     should assume that it may someday grow to at most 256 characters
     in length.

`COMMITID'
     Unique Session ID of the CVS process. This is a random string of
     printable characters of at least 16 characters length. Users
     should assume that it may someday grow to at most 256 characters
     in length.

   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' (*note ~/.cvsrc::).

   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'
     The CVS-specific username provided by the user, if it can be
     provided (currently just for the pserver access method), and to
     the empty string otherwise.  (`CVS_USER' and `USER' may differ
     when `$CVSROOT/CVSROOT/passwd' is used to map CVS usernames to
     system usernames.)

`LOGNAME'
     The username of the system user.

`USER'
     Same as `LOGNAME'.  Do not confuse this with the internal variable
     of the same name.


File: cvs.info,  Node: config,  Prev: Variables,  Up: Administrative files

The CVSROOT/config configuration file
=====================================

   Usually, the `config' file is found at `$CVSROOT/CVSROOT/config',
but this may be overridden on the `pserver' and `server' command lines
(*note server & pserver::).

   The administrative file `config' contains various miscellaneous
settings which affect the behavior of CVS.  The syntax is slightly
different from the other administrative files.

   Leading white space on any line is ignored, though the syntax is
very strict and will reject spaces and tabs almost anywhere else.

   Empty lines, lines containing nothing but white space, and lines
which start with `#' (discounting any leading white space) are ignored.

   Other lines consist of the optional leading white space, a keyword,
`=', and a value.  Please note again that this syntax is very strict.
Extraneous spaces or tabs, other than the leading white space, are not
permitted on these lines.

   As of CVS 1.12.13, lines of the form `[CVSROOT]' mark the subsequent
section of the config file as applying only to certain repositories.
Multiple `[CVSROOT]' lines without intervening `KEYWORD=VALUE' pairs
cause processing to fall through, processing subsequent keywords for
any root in the list.  Finally, keywords and values which appear before
any `[CVSROOT]' lines are defaults, and may to apply to any repository.
For example, consider the following file:

     # Defaults
     LogHistory=TMAR
     
     [/cvsroots/team1]
       LockDir=/locks/team1
     
     [/cvsroots/team2]
       LockDir=/locks/team2
     
     [/cvsroots/team3]
       LockDir=/locks/team3
     
     [/cvsroots/team4]
       LockDir=/locks/team4
     
     [/cvsroots/team3]
     [/cvsroots/team4]
       # Override logged commands for teams 3 & 4.
       LogHistory=all

   This example file sets up separate lock directories for each
project, as well as a default set of logged commands overridden for the
example's team 3 & team 4. This syntax could be useful, for instance,
if you wished to share a single config file, for instance
`/etc/cvs.conf', among several repositories.

   Currently defined keywords are:

`HistorySearchPath=PATTERN'
     Request that CVS look for its history information in files matching
     PATTERN, which is a standard UNIX file glob.  If PATTERN matches
     multiple files, all will be searched in lexicographically sorted
     order.  *Note history::, and *Note history file::, for more.

     If no value is supplied for this option, it defaults to
     `$CVSROOT/CVSROOT/history'.

`HistoryLogPath=PATH'
     Control where CVS logs its history.  If the file does not exist,
     CVS will attempt to create it.  Format strings, as available to
     the GNU C `strftime' function and often the UNIX date command, and
     the string $CVSROOT will be substituted in this path.  For
     example, consider the line:

          HistoryLogPath=$CVSROOT/CVSROOT/history/%Y-%m-%d

     This line would cause CVS to attempt to create its history file in
     a subdirectory (`history') of the configuration directory
     (`CVSROOT') with a name equal to the current date representation
     in the ISO8601 format (for example, on May 11, 2005, CVS would
     attempt to log its history under the repository root directory in
     a file named `CVSROOT/history/2005-05-11').  *Note history::, and
     *Note history file::, for more.

     If no value is supplied for this option, it defaults to
     `$CVSROOT/CVSROOT/history'.

`ImportNewFilesToVendorBranchOnly=VALUE'
     Specify whether `cvs import' should always behave as if the `-X'
     flag was specified on the command line.  VALUE may be either `yes'
     or `no'.  If set to `yes', all uses of `cvs import' on the
     repository will behave as if the `-X' flag was set.  The default
     value is `no'.

`KeywordExpand=VALUE'
     Specify `i' followed by a list of keywords to be expanded (for
     example, `KeywordExpand=iMYCVS,Name,Date'), or `e' followed by a
     list of keywords not to be expanded (for example,
     `KeywordExpand=eCVSHeader').  For more on keyword expansion, see
     *Note Configuring keyword expansion::.

`LocalKeyword=VALUE'
     Specify a local alias for a standard keyword.  For example,
     `LocalKeyword=MYCVS=CVSHeader'.  For more on local keywords, see
     *Note Keyword substitution::.

`LockDir=DIRECTORY'
     Put CVS lock files in DIRECTORY rather than directly in the
     repository.  This is useful if you want to let users read from the
     repository while giving them write access only to DIRECTORY, not
     to the repository.  It can also be used to put the locks on a very
     fast in-memory file system to speed up locking and unlocking the
     repository.  You need to create DIRECTORY, but CVS will create
     subdirectories of DIRECTORY as it needs them.  For information on
     CVS locks, see *Note Concurrency::.

     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'
     Control what is logged to the `CVSROOT/history' file (*note
     history::).  Default of `TOEFWUPCGMAR' (or simply `all') will log
     all transactions.  Any subset of the default is legal.  (For
     example, to only log transactions that modify the `*,v' files, use
     `LogHistory=TMAR'.)  To disable history logging completely, use
     `LogHistory='.

`MaxCommentLeaderLength=LENGTH'
     Set to some length, in bytes, where a trailing `k', `M', `G', or
     `T' causes the preceding nubmer to be interpreted as kilobytes,
     megabytes, gigabytes, or terrabytes, respectively, will cause
     `$Log$' keywords (*note Keyword substitution::), with more than
     LENGTH bytes preceding it on a line to be ignored (or to fall back
     on the comment leader set in the RCS archive file - see
     `UseArchiveCommentLeader' below).  Defaults to 20 bytes to allow
     checkouts to proceed normally when they include binary files
     containing `$Log$' keywords and which users have neglected to mark
     as binary.

`MinCompressionLevel=VALUE'
`MaxCompressionLevel=VALUE'
     Restricts the level of compression used by the CVS server to a
     VALUE between 0 and 9.  VALUEs 1 through 9 are the same ZLIB
     compression levels accepted by the `-z' option (*note Global
     options::), and 0 means no compression.  When one or both of these
     keys are set and a client requests a level outside the specified
     range, the server will simply use the closest permissable level.
     Clients will continue compressing at the level requested by the
     user.

     The exception is when level 0 (no compression) is not available
     and the client fails to request any compression.  The CVS server
     will then exit with an error message when it becomes apparent that
     the client is not going to request compression.  This will not
     happen with clients version 1.12.13 and later since these client
     versions allow the server to notify them that they must request
     some level of compression.

`PrimaryServer=CVSROOT'
     When specified, and the repository specified by CVSROOT is not the
     one currently being accessed, then the server will turn itself
     into a transparent proxy to CVSROOT for write requests.  The
     HOSTNAME configured as part of CVSROOT must resolve to the same
     string returned by the `uname' command on the primary server for
     this to work.  Host name resolution is performed via some
     combination of `named', a broken out line from `/etc/hosts', and
     the Network Information Service (NIS or YP), depending on the
     configuration of the particular system.

     Only the `:ext:' method is currently supported for primaries
     (actually, `:fork:' is supported as well, but only for testing -
     if you find another use for accessing a primary via the `:fork:'
     method, please send a note to <bug-cvs@nongnu.org> about it).  See
     *Note Write proxies:: for more on configuring and using write
     proxies.

`RCSBIN=BINDIR'
     For CVS 1.9.12 through 1.9.18, this setting told CVS to look for
     RCS programs in the BINDIR directory.  Current versions of CVS do
     not run RCS programs; for compatibility this setting is accepted,
     but it does nothing.

`RereadLogAfterVerify=VALUE'
     Modify the `commit' command such that CVS will reread the log
     message after running the program specified by `verifymsg'.  VALUE
     may be one of `yes' or `always', indicating that the log message
     should always be reread; `no' or `never', indicating that it
     should never be reread; or VALUE may be `stat', indicating that
     the file should be checked with the file system `stat()' function
     to see if it has changed (see warning below) before rereading.
     The default value is `always'.

     *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*

     *Note verifymsg::, for more information on how verifymsg may be
     used.

`SystemAuth=VALUE'
     If VALUE is `yes', then pserver should check for users in the
     system's user database if not found in `CVSROOT/passwd'.  If it is
     `no', then all pserver users must exist in `CVSROOT/passwd'.  The
     default is `yes'.  For more on pserver, see *Note Password
     authenticated::.

`TmpDir=PATH'
     Specify PATH as the directory to create temporary files in.  *Note
     Global options::, for more on setting the path to the temporary
     directory.  This option first appeared with CVS release 1.12.13.

`TopLevelAdmin=VALUE'
     Modify the `checkout' command to create a `CVS' directory at the
     top level of the new working directory, in addition to `CVS'
     directories created within checked-out directories.  The default
     value is `no'.

     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 (*note Working directory storage::).

`UseArchiveCommentLeader=VALUE'
     Set to `true', if the text preceding a `$Log$' keyword is found to
     exceed `MaxCommentLeaderLength' (above) bytes, then the comment
     leader set in the RCS archive file (*note admin::), if any, will
     be used instead.  If there is no comment leader set in the archive
     file or VALUE is set to `false', then the keyword will not be
     expanded (*note Keyword list::).  To force the comment leader in
     the RCS archive file to be used exclusively (and `$Log$' expansion
     skipped in files where the comment leader has not been set in the
     archive file), set VALUE and set `MaxCommentLeaderLength' to `0'.

`UseNewInfoFmtStrings=VALUE'
     Specify whether CVS should support the new or old command line
     template model for the commit support files (*note commit files::).
     This configuration variable began life in deprecation and is only
     here in order to give people time to update legacy repositories to
     use the new format string syntax before support for the old syntax
     is removed.  For information on updating your repository to
     support the new model, please see *Note Updating Commit Files::.

     _Note that new repositories (created with the `cvs init' command)
     will have this value set to `yes', but the default value is `no'._

`UserAdminOptions=VALUE'
     Control what options will be allowed with the `cvs admin' command
     (*note admin::) 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 (*note admin::).

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

