<div id="Administrative-files"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[cvs: Quick reference to CVS commands#Invoking-CVS  &lt; ]|</td>
<td valign="middle" align="left">|[[#modules| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[cvs: Quick reference to CVS commands#Invoking-CVS  &lt;&lt; ]|</td>
<td valign="middle" align="left">|[[cvs#Top| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Reference-manual-for-Administrative-files"></div>
== Reference manual for Administrative files ==
<div id="index-Administrative-files-_0028reference_0029"></div>
<div id="index-Files_002c-reference-manual"></div>
<div id="index-Reference-manual-_0028files_0029"></div>
<div id="index-CVSROOT-_0028file_0029"></div>

<p>Inside the repository, in the directory
&lsquo;<tt>$CVSROOT/CVSROOT</tt>&rsquo;, there are a number of
supportive files for <small>CVS</small>.  You can use <small>CVS</small> 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 [cvs: The Repository#Intro-administrative-files The administrative files].
</p>
<p>The most important of these files is the &lsquo;<tt>modules</tt>&rsquo;
file, which defines the modules inside the repository.
</p>
<pre class="menu-preformatted"><nowiki></nowiki>&bull;[[#modules| modules]]::<nowiki>                     Defining modules
</nowiki>&bull;[[#Wrappers| Wrappers]]::<nowiki>                    Specify binary-ness based on file name
</nowiki>&bull;[[#commit-files| commit files]]::<nowiki>                The commit support files (commitinfo,
                                verifymsg, editinfo, loginfo)
</nowiki>&bull;[[#rcsinfo| rcsinfo]]::<nowiki>                     Templates for the log messages
</nowiki>&bull;[[#cvsignore| cvsignore]]::<nowiki>                   Ignoring files via cvsignore
</nowiki>&bull;[[#checkoutlist| checkoutlist]]::<nowiki>                Adding your own administrative files
</nowiki>&bull;[[#history-file| history file]]::<nowiki>                History information
</nowiki>&bull;[[#Variables| Variables]]::<nowiki>                   Various variables are expanded
</nowiki>&bull;[[#config| config]]::<nowiki>                      Miscellaneous CVS configuration
</nowiki></pre>
<hr size="6">
<div id="modules"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Administrative-files| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Alias-modules| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Administrative-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="The-modules-file"></div>
=== The modules file ===
<div id="index-Modules-_0028admin-file_0029"></div>
<div id="index-Defining-modules-_0028reference-manual_0029"></div>

<p>The &lsquo;<tt>modules</tt>&rsquo; file records your definitions of
names for collections of source code.  <small>CVS</small> will
use these definitions if you use <small>CVS</small> to update the
modules file (use normal commands like <code>add</code>,
<code>commit</code>, etc).
</p>
<p>The &lsquo;<tt>modules</tt>&rsquo; file may contain blank lines and
comments (lines beginning with &lsquo;<samp>#</samp>&rsquo;) as well as
module definitions.  Long lines can be continued on the
next line by specifying a backslash (&lsquo;<samp>\</samp>&rsquo;) as the
last character on the line.
</p>
<p>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 &lsquo;<tt>first-dir</tt>&rsquo;, which
contains two files, &lsquo;<tt>file1</tt>&rsquo; and &lsquo;<tt>file2</tt>&rsquo;, and a
directory &lsquo;<tt>sdir</tt>&rsquo;.  &lsquo;<tt>first-dir/sdir</tt>&rsquo; contains
a file &lsquo;<tt>sfile</tt>&rsquo;.
</p>

<pre class="menu-preformatted"><nowiki></nowiki>&bull;[[#Alias-modules| Alias modules]]::<nowiki>             The simplest kind of module
</nowiki>&bull;[[#Regular-modules| Regular modules]]::<nowiki>
</nowiki>&bull;[[#Ampersand-modules| Ampersand modules]]::<nowiki>
</nowiki>&bull;[[#Excluding-directories| Excluding directories]]::<nowiki>     Excluding directories from a module
</nowiki>&bull;[[#Module-options| Module options]]::<nowiki>            Regular and ampersand modules can take options
</nowiki>&bull;[[#Module-program-options| Module program options]]::<nowiki>    How the modules &ldquo;program options&rdquo; programs
                              are run. 
</nowiki></pre>
<hr size="6">
<div id="Alias-modules"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#modules| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Regular-modules| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#modules| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Alias-modules-1"></div>
==== Alias modules ====
<div id="index-Alias-modules"></div>
<div id="index-_002da_002c-in-modules-file"></div>

<p>Alias modules are the simplest kind of module:
</p>
<dl compact="compact">
<dt> <code><var>mname</var> -a <var>aliases</var>&hellip;</code></dt>
<dd><p>This represents the simplest way of defining a module
<var>mname</var>.  The &lsquo;<samp>-a</samp>&rsquo; flags the definition as a
simple alias: <small>CVS</small> will treat any use of <var>mname</var> (as
a command argument) as if the list of names
<var>aliases</var> had been specified instead.
<var>aliases</var> may contain either other module names or
paths.  When you use paths in aliases, <code>checkout</code>
creates all intermediate directories in the working
directory, just as if the path had been specified
explicitly in the <small>CVS</small> arguments.
</p></dd>
</dl>

<p>For example, if the modules file contains:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>amodule -a first-dir
</nowiki></pre></td></tr></table>

<p>then the following two commands are equivalent:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs co amodule
$ cvs co first-dir
</nowiki></pre></td></tr></table>

<p>and they each would provide output such as:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>cvs checkout: Updating first-dir
U first-dir/file1
U first-dir/file2
cvs checkout: Updating first-dir/sdir
U first-dir/sdir/sfile
</nowiki></pre></td></tr></table>

<hr size="6">
<div id="Regular-modules"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Alias-modules| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Ampersand-modules| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#modules| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Regular-modules-1"></div>
==== Regular modules ====
<div id="index-Regular-modules"></div>

<dl compact="compact">
<dt> <code><var>mname</var> [ options ] <var>dir</var> [ <var>files</var>&hellip; ]</code></dt>
<dd><p>In the simplest case, this form of module definition
reduces to &lsquo;<samp><var>mname</var> <var>dir</var></samp>&rsquo;.  This defines
all the files in directory <var>dir</var> as module mname.
<var>dir</var> is a relative path (from <code>$CVSROOT</code>) to a
directory of source in the source repository.  In this
case, on checkout, a single directory called
<var>mname</var> is created as a working directory; no
intermediate directory levels are used by default, even
if <var>dir</var> was a path involving several directory
levels.
</p></dd>
</dl>

<p>For example, if a module is defined by:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>regmodule first-dir
</nowiki></pre></td></tr></table>

<p>then regmodule will contain the files from first-dir:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs co regmodule
cvs checkout: Updating regmodule
U regmodule/file1
U regmodule/file2
cvs checkout: Updating regmodule/sdir
U regmodule/sdir/sfile
$
</nowiki></pre></td></tr></table>

<p>By explicitly specifying files in the module definition
after <var>dir</var>, you can select particular files from
directory <var>dir</var>.  Here is
an example:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>regfiles first-dir/sdir sfile
</nowiki></pre></td></tr></table>

<p>With this definition, getting the regfiles module
will create a single working directory
&lsquo;<tt>regfiles</tt>&rsquo; containing the file listed, which
comes from a directory deeper
in the <small>CVS</small> source repository:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs co regfiles
U regfiles/sfile
$
</nowiki></pre></td></tr></table>

<hr size="6">
<div id="Ampersand-modules"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Regular-modules| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Excluding-directories| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#modules| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Ampersand-modules-1"></div>
==== Ampersand modules ====
<div id="index-Ampersand-modules"></div>
<div id="index-_0026_002c-in-modules-file"></div>

<p>A module definition can refer to other modules by
including &lsquo;<samp>&amp;<var>module</var></samp>&rsquo; in its definition.
</p><table><tr><td>&nbsp;</td><td><pre class="example"><nowiki><var>mname</var> [ options ] <var>&amp;module</var>&hellip;
</nowiki></pre></td></tr></table>

<p>Then getting the module creates a subdirectory for each such
module, in the directory containing the module.  For
example, if modules contains
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>ampermod &amp;first-dir
</nowiki></pre></td></tr></table>

<p>then a checkout will create an <code>ampermod</code> directory
which contains a directory called <code>first-dir</code>,
which in turns contains all the directories and files
which live there.  For example, the command
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ cvs co ampermod
</nowiki></pre></td></tr></table>

<p>will create the following files:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>ampermod/first-dir/file1
ampermod/first-dir/file2
ampermod/first-dir/sdir/sfile
</nowiki></pre></td></tr></table>

<p>There is one quirk/bug: the messages that <small>CVS</small>
prints omit the &lsquo;<tt>ampermod</tt>&rsquo;, and thus do not
correctly display the location to which it is checking
out the files:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ 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
$
</nowiki></pre></td></tr></table>

<p>Do not rely on this buggy behavior; it may get fixed in
a future release of <small>CVS</small>.
</p>

<hr size="6">
<div id="Excluding-directories"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Ampersand-modules| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Module-options| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#modules| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Excluding-directories-1"></div>
==== Excluding directories ====
<div id="index-Excluding-directories_002c-in-modules-file"></div>
<div id="index-_0021_002c-in-modules-file"></div>

<p>An alias module may exclude particular directories from
other modules by using an exclamation mark (&lsquo;<samp>!</samp>&rsquo;)
before the name of each directory to be excluded.
</p>
<p>For example, if the modules file contains:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>exmodule -a !first-dir/sdir first-dir
</nowiki></pre></td></tr></table>

<p>then checking out the module &lsquo;<samp>exmodule</samp>&rsquo; will check
out everything in &lsquo;<samp>first-dir</samp>&rsquo; except any files in
the subdirectory &lsquo;<samp>first-dir/sdir</samp>&rsquo;.
</p>
<hr size="6">
<div id="Module-options"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Excluding-directories| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Module-program-options| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#modules| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Module-options-1"></div>
==== Module options ====
<div id="index-Options_002c-in-modules-file"></div>

<p>Either regular modules or ampersand modules can contain
options, which supply additional information concerning
the module.
</p>
<dl compact="compact">
<dd><div id="index-_002dd_002c-in-modules-file"></div>
</dd>
<dt> <code>-d <var>name</var></code></dt>
<dd><p>Name the working directory something other than the
module name.
</p>
<div id="index-Export-program"></div>
<div id="index-_002de_002c-in-modules-file"></div>
</dd>
<dt> <code>-e <var>prog</var></code></dt>
<dd><p>Specify a program <var>prog</var> to run whenever files in a
module are exported.  <var>prog</var> runs with a single
argument, the module name.
</p>
<div id="index-Checkout-program"></div>
<div id="index-_002do_002c-in-modules-file"></div>
</dd>
<dt> <code>-o <var>prog</var></code></dt>
<dd><p>Specify a program <var>prog</var> to run whenever files in a
module are checked out.  <var>prog</var> runs with a single
argument, the module name.  See [[#Module-program-options|How the modules file &ldquo;program options&rdquo; programs are run]] for
information on how <var>prog</var> is called.
</p>
<div id="index-Status-of-a-module"></div>
<div id="index-Module-status"></div>
<div id="index-_002ds_002c-in-modules-file"></div>
</dd>
<dt> <code>-s <var>status</var></code></dt>
<dd><p>Assign a status to the module.  When the module file is
printed with &lsquo;<samp>cvs checkout -s</samp>&rsquo; the modules are
sorted according to primarily module status, and
secondarily according to the module name.  This option
has no other meaning.  You can use this option for
several things besides status: for instance, list the
person that is responsible for this module.
</p>
<div id="index-Tag-program"></div>
<div id="index-_002dt_002c-in-modules-file"></div>
</dd>
<dt> <code>-t <var>prog</var></code></dt>
<dd><p>Specify a program <var>prog</var> to run whenever files in a
module are tagged with <code>rtag</code>.  <var>prog</var> runs
with two arguments: the module name and the symbolic
tag specified to <code>rtag</code>.  It is not run
when <code>tag</code> is executed.  Generally you will find
that taginfo is a better solution (see section [cvs: History browsing#user_002ddefined-logging User-defined logging]).
</p></dd>
</dl>

<p>You should also see see section [[#Module-program-options|How the modules file &ldquo;program options&rdquo; programs are run]] about how the
&ldquo;program options&rdquo; programs are run.
</p>

<hr size="6">
<div id="Module-program-options"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Module-options| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Wrappers| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#modules| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="How-the-modules-file-_0060_0060program-options_0027_0027-programs-are-run"></div>
==== How the modules file &ldquo;program options&rdquo; programs are run ====
<div id="index-Modules-file-program-options"></div>
<div id="index-_002dt_002c-in-modules-file-1"></div>
<div id="index-_002do_002c-in-modules-file-1"></div>
<div id="index-_002de_002c-in-modules-file-1"></div>

<p>For checkout, rtag, and export, the program is server-based, and as such the
following applies:-
</p>
<p>If using remote access methods (pserver, ext, etc.),
<small>CVS</small> will execute this program on the server from a temporary
directory. The path is searched for this program.
</p>
<p>If using &ldquo;local access&rdquo; (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.
</p>
<p>The programs are all run after the operation has effectively
completed.
</p>

<hr size="6">
<div id="Wrappers"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Module-program-options| &lt; ]]|</td>
<td valign="middle" align="left">|[[#commit-files| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Administrative-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="The-cvswrappers-file"></div>
=== The cvswrappers file ===
<div id="index-cvswrappers-_0028admin-file_0029"></div>
<div id="index-CVSWRAPPERS_002c-environment-variable"></div>
<div id="index-Wrappers"></div>


<p>Wrappers refers to a <small>CVS</small> feature which lets you
control certain settings based on the name of the file
which is being operated on.  The settings are &lsquo;<samp>-k</samp>&rsquo;
for binary files, and &lsquo;<samp>-m</samp>&rsquo; for nonmergeable text
files.
</p>
<p>The &lsquo;<samp>-m</samp>&rsquo; option
specifies the merge methodology that should be used when
a non-binary file is updated.  <code>MERGE</code> means the usual
<small>CVS</small> behavior: try to merge the files.  <code>COPY</code>
means that <code>cvs update</code> will refuse to merge
files, as it also does for files specified as binary
with &lsquo;<samp>-kb</samp>&rsquo; (but if the file is specified as
binary, there is no need to specify &lsquo;<samp>-m 'COPY'</samp>&rsquo;).
<small>CVS</small> will provide the user with the
two versions of the files, and require the user using
mechanisms outside <small>CVS</small>, to insert any necessary
changes.
</p>
<p><strong>WARNING: do not use <code>COPY</code> with
<small>CVS</small> 1.9 or earlier - such versions of <small>CVS</small> will
copy one version of your file over the other, wiping
out the previous contents.</strong>
The &lsquo;<samp>-m</samp>&rsquo; wrapper option only affects behavior when
merging is done on update; it does not affect how files
are stored.  See [cvs: Handling binary files#Binary-files Handling binary files], for more on
binary files.
</p>
<p>The basic format of the file &lsquo;<tt>cvswrappers</tt>&rsquo; is:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>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.
</nowiki></pre></td></tr></table>


<p>For example, the following command imports a
directory, treating files whose name ends in
&lsquo;<samp>.exe</samp>&rsquo; as binary:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>cvs import -I ! -W &quot;*.exe -k 'b'&quot; first-dir vendortag reltag
</nowiki></pre></td></tr></table>


<hr size="6">
<div id="commit-files"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Wrappers| &lt; ]]|</td>
<td valign="middle" align="left">|[[#syntax| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Administrative-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="The-commit-support-files"></div>
=== The commit support files ===
<div id="index-Committing_002c-administrative-support-files"></div>

<p>The &lsquo;<samp>-i</samp>&rsquo; flag in the &lsquo;<tt>modules</tt>&rsquo; file can be
used to run a certain program whenever files are
committed (see section [[#modules|The modules file]]).  The files described in
this section provide other, more flexible, ways to run
programs whenever something is committed.
</p>
<p>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.
</p>
<dl compact="compact">
<dt> &lsquo;<tt>commitinfo</tt>&rsquo;</dt>
<dd><p>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.
</p>
</dd>
<dt> &lsquo;<tt>verifymsg</tt>&rsquo;</dt>
<dd><p>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
&lsquo;<tt>rcsinfo</tt>&rsquo; file, which can hold a log message
template (see section [[#rcsinfo|Rcsinfo]]).
</p>
</dd>
<dt> &lsquo;<tt>editinfo</tt>&rsquo;</dt>
<dd><p>The specified program is used to edit the log message,
and possibly verify that it contains all required
fields.  This is most useful in combination with the
&lsquo;<tt>rcsinfo</tt>&rsquo; file, which can hold a log message
template (see section [[#rcsinfo|Rcsinfo]]).  (obsolete)
</p>
</dd>
<dt> &lsquo;<tt>loginfo</tt>&rsquo;</dt>
<dd><p>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&hellip;  Your
imagination is the limit!
</p></dd>
</dl>

<pre class="menu-preformatted"><nowiki></nowiki>&bull;[[#syntax| syntax]]::<nowiki>                      The common syntax
</nowiki>&bull;[[#commitinfo| commitinfo]]::<nowiki>                  Pre-commit checking
</nowiki>&bull;[[#verifymsg| verifymsg]]::<nowiki>                   How are log messages evaluated?
</nowiki>&bull;[[#editinfo| editinfo]]::<nowiki>                    Specifying how log messages are created
                                (obsolete)
</nowiki>&bull;[[#loginfo| loginfo]]::<nowiki>                     Where should log messages be sent?
</nowiki></pre>
<hr size="6">
<div id="syntax"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#commit-files| &lt; ]]|</td>
<td valign="middle" align="left">|[[#commitinfo| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#commit-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="The-common-syntax"></div>
==== The common syntax ====
<div id="index-Info-files-_0028syntax_0029"></div>
<div id="index-Syntax-of-info-files"></div>
<div id="index-Common-syntax-of-info-files"></div>


<p>The administrative files such as &lsquo;<tt>commitinfo</tt>&rsquo;,
&lsquo;<tt>loginfo</tt>&rsquo;, &lsquo;<tt>rcsinfo</tt>&rsquo;, &lsquo;<tt>verifymsg</tt>&rsquo;, etc.,
all have a common format.  The purpose of the files are
described later on.  The common syntax is described
here.
</p>
<div id="index-Regular-expression-syntax"></div>
<p>Each line contains the following:
</p><ul>
<li>
A regular expression.  This is a basic regular
expression in the syntax used by GNU emacs.

</li><li>
A whitespace separator&mdash;one or more spaces and/or tabs.

</li><li>
A file name or command-line template.
</li></ul>

<p>Blank lines are ignored.  Lines that start with the
character &lsquo;<samp>#</samp>&rsquo; are treated as comments.  Long lines
unfortunately can <em>not</em> be broken in two parts in
any way.
</p>
<p>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.
</p>

<hr size="6">
<div id="commitinfo"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#syntax| &lt; ]]|</td>
<td valign="middle" align="left">|[[#verifymsg| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#commit-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Commitinfo"></div>
==== Commitinfo ====
<div id="index-commitinfo"></div>
<div id="index-Commits_002c-precommit-verification-of"></div>
<div id="index-Precommit-checking"></div>

<p>The &lsquo;<tt>commitinfo</tt>&rsquo; file defines programs to execute
whenever &lsquo;<samp>cvs commit</samp>&rsquo; 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&rsquo;s standards for coding practice.
</p>
<p>As mentioned earlier, each line in the
&lsquo;<tt>commitinfo</tt>&rsquo; 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).
</p>
<div id="index-Exit-status_002c-of-commitinfo"></div>
<p>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.
</p>
<div id="index-DEFAULT-in-commitinfo"></div>
<p>If the repository name does not match any of the
regular expressions in this file, the &lsquo;<samp>DEFAULT</samp>&rsquo;
line is used, if it is specified.
</p>
<div id="index-ALL-in-commitinfo"></div>
<p>All occurrences of the name &lsquo;<samp>ALL</samp>&rsquo; appearing as a
regular expression are used in addition to the first
matching regular expression or the name &lsquo;<samp>DEFAULT</samp>&rsquo;.
</p>
<div id="index-commitinfo_002c-working-directory"></div>
<div id="index-commitinfo_002c-command-environment"></div>
<p>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), <em>or in a copy of the workspace on
the server (see section [cvs: The Repository#Remote-repositories Remote repositories])</em>.  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.
</p>
<p>Note that both the repository directory and the corresponding
Attic (see section [cvs: The Repository#Attic 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.
</p>

<hr size="6">
<div id="verifymsg"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#commitinfo| &lt; ]]|</td>
<td valign="middle" align="left">|[[#editinfo| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#commit-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Verifying-log-messages"></div>
==== Verifying log messages ====
<div id="index-verifymsg-_0028admin-file_0029"></div>
<div id="index-Log-message_002c-verifying"></div>

<p>Once you have entered a log message, you can evaluate
that message to check for specific content, such as
a bug ID.  Use the &lsquo;<tt>verifymsg</tt>&rsquo; 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.
</p>
<p>The &lsquo;<tt>verifymsg</tt>&rsquo; file is often most useful together
with the &lsquo;<tt>rcsinfo</tt>&rsquo; file, which can be used to
specify a log message template.
</p>
<p>Each line in the &lsquo;<tt>verifymsg</tt>&rsquo; 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.
</p>
<p>One thing that should be noted is that the &lsquo;<samp>ALL</samp>&rsquo;
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.
</p>
<div id="index-DEFAULT-in-verifymsg"></div>
<p>If the repository name does not match any of the
regular expressions in this file, the &lsquo;<samp>DEFAULT</samp>&rsquo;
line is used, if it is specified.
</p>
<div id="index-Exit-status_002c-of-verifymsg"></div>
<p>If the verification script exits with a non-zero exit status,
the commit is aborted.
</p>
<div id="index-verifymsg_002c-changing-the-log-message"></div>
<p>In the default configuration, CVS allows the
verification script to change the log message. This is
controlled via the RereadLogAfterVerify CVSROOT/config
option.
</p>
<p>When &lsquo;<samp>RereadLogAfterVerify=always</samp>&rsquo; or
&lsquo;<samp>RereadLogAfterVerify=stat</samp>&rsquo;, 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.
</p>
<p>See section [[#config|The CVSROOT/config configuration file]], for more on CVSROOT/config options.
</p>
<p>It is NOT a good idea for a &lsquo;<tt>verifymsg</tt>&rsquo; script to
interact directly with the user in the various
client/server methods. For the <code>pserver</code> method,
there is no protocol support for communicating between
&lsquo;<tt>verifymsg</tt>&rsquo; and the client on the remote end. For the
<code>ext</code> and <code>server</code> methods, it is possible
for CVS to become confused by the characters going
along the same channel as the CVS protocol
messages. See [cvs: The Repository#Remote-repositories Remote repositories], for more
information on client/server setups.  In addition, at the time
the &lsquo;<tt>verifymsg</tt>&rsquo; 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.
</p>
<p>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 &lsquo;<tt>verifymsg</tt>&rsquo;.
</p>
<p>An example of an update might be to change all
occurrences of &rsquo;BugId:&rsquo; to be &rsquo;DefectId:&rsquo; (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).
</p>
<p>Another example of an update might be to delete a line
that contains &rsquo;BugID: none&rsquo; from the log message after
validation of that value as being allowed is made.
</p>
<p>The following is a little silly example of a
&lsquo;<tt>verifymsg</tt>&rsquo; file, together with the corresponding
&lsquo;<tt>rcsinfo</tt>&rsquo; file, the log message template and an
verification  script.  We begin with the log message template.
We want to always record a bug-id number on the first
line of the log message.  The rest of log message is
free text.  The following template is found in the file
&lsquo;<tt>/usr/cvssupport/tc.template</tt>&rsquo;.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>BugId:
</nowiki></pre></td></tr></table>

<p>The script &lsquo;<tt>/usr/cvssupport/bugid.verify</tt>&rsquo; is used to
evaluate the log message.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>#!/bin/sh
#
#       bugid.verify filename
#
#  Verify that the log message contains a valid bugid
#  on the first line.
#
if head -1 &lt; $1 | grep '^BugId:[ ]*[0-9][0-9]*$' &gt; /dev/null; then
    exit 0
elif head -1 &lt; $1 | grep '^BugId:[ ]*none$' &gt; /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$' &gt; $1.rewrite
    mv $1.rewrite $1
    exit 0
else
    echo &quot;No BugId found.&quot;
    exit 1
fi
</nowiki></pre></td></tr></table>

<p>The &lsquo;<tt>verifymsg</tt>&rsquo; file contains this line:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>^tc     /usr/cvssupport/bugid.verify
</nowiki></pre></td></tr></table>

<p>The &lsquo;<tt>rcsinfo</tt>&rsquo; file contains this line:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>^tc     /usr/cvssupport/tc.template
</nowiki></pre></td></tr></table>

<p>The &lsquo;<tt>config</tt>&rsquo; file contains this line:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>RereadLogAfterVerify=always
</nowiki></pre></td></tr></table>



<hr size="6">
<div id="editinfo"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#verifymsg| &lt; ]]|</td>
<td valign="middle" align="left">|[[#editinfo-example| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#commit-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Editinfo"></div>
==== Editinfo ====
<div id="index-editinfo-_0028admin-file_0029"></div>
<div id="index-Editor_002c-specifying-per-module"></div>
<div id="index-Per_002dmodule-editor"></div>
<div id="index-Log-messages_002c-editing"></div>

<p><strong>Note: The &lsquo;<tt>editinfo</tt>&rsquo; feature has been
rendered obsolete.  To set a default editor for log
messages use the <code>CVSEDITOR</code>, <code>EDITOR</code> environment variables
(see section [cvs: All environment variables which affect CVS#Environment-variables All environment variables which affect CVS]) or the &lsquo;<samp>-e</samp>&rsquo; global
option (see section [cvs: Guide to CVS commands#Global-options Global options]).  See [[#verifymsg|Verifying log messages]],
for information on the use of the &lsquo;<tt>verifymsg</tt>&rsquo;
feature for evaluating log messages.</strong>
</p>
<p>If you want to make sure that all log messages look the
same way, you can use the &lsquo;<tt>editinfo</tt>&rsquo; 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.
</p>
<p>If no matching line is found in the &lsquo;<tt>editinfo</tt>&rsquo;
file, the editor specified in the environment variable
<code>$CVSEDITOR</code> is used instead.  If that variable is
not set, then the environment variable <code>$EDITOR</code>
is used instead.  If that variable is not
set a default will be used.  See [cvs: Overview#Committing-your-changes Committing your changes].
</p>
<p>The &lsquo;<tt>editinfo</tt>&rsquo; file is often most useful together
with the &lsquo;<tt>rcsinfo</tt>&rsquo; file, which can be used to
specify a log message template.
</p>
<p>Each line in the &lsquo;<tt>editinfo</tt>&rsquo; 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.
</p>
<p>One thing that should be noted is that the &lsquo;<samp>ALL</samp>&rsquo;
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.
</p>
<div id="index-DEFAULT-in-editinfo"></div>
<p>If the repository name does not match any of the
regular expressions in this file, the &lsquo;<samp>DEFAULT</samp>&rsquo;
line is used, if it is specified.
</p>
<p>If the edit script exits with a non-zero exit status,
the commit is aborted.
</p>
<p>Note: when <small>CVS</small> is accessing a remote repository,
or when the &lsquo;<samp>-m</samp>&rsquo; or &lsquo;<samp>-F</samp>&rsquo; options to <code>cvs
commit</code> are used, &lsquo;<tt>editinfo</tt>&rsquo; will not be consulted.
There is no good workaround for this; use
&lsquo;<tt>verifymsg</tt>&rsquo; instead.
</p>
<pre class="menu-preformatted"><nowiki></nowiki>&bull;[[#editinfo-example| editinfo example]]::<nowiki>            Editinfo example
</nowiki></pre>
<hr size="6">
<div id="editinfo-example"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#editinfo| &lt; ]]|</td>
<td valign="middle" align="left">|[[#loginfo| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#editinfo| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Editinfo-example"></div>
===== Editinfo example =====

<p>The following is a little silly example of a
&lsquo;<tt>editinfo</tt>&rsquo; file, together with the corresponding
&lsquo;<tt>rcsinfo</tt>&rsquo; 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
&lsquo;<tt>/usr/cvssupport/tc.template</tt>&rsquo;.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>BugId:
</nowiki></pre></td></tr></table>

<p>The script &lsquo;<tt>/usr/cvssupport/bugid.edit</tt>&rsquo; is used to
edit the log message.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>#!/bin/sh
#
#       bugid.edit filename
#
#  Call $EDITOR on FILENAME, and verify that the
#  resulting file contains a valid bugid on the first
#  line.
if [ &quot;x$EDITOR&quot; = &quot;x&quot; ]; then EDITOR=vi; fi
if [ &quot;x$CVSEDITOR&quot; = &quot;x&quot; ]; then CVSEDITOR=$EDITOR; fi
$CVSEDITOR $1
until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' &lt; $1
do  echo -n  &quot;No BugId found.  Edit again? ([y]/n)&quot;
    read ans
    case ${ans} in
        n*) exit 1;;
    esac
    $CVSEDITOR $1
done
</nowiki></pre></td></tr></table>

<p>The &lsquo;<tt>editinfo</tt>&rsquo; file contains this line:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>^tc     /usr/cvssupport/bugid.edit
</nowiki></pre></td></tr></table>

<p>The &lsquo;<tt>rcsinfo</tt>&rsquo; file contains this line:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>^tc     /usr/cvssupport/tc.template
</nowiki></pre></td></tr></table>

<hr size="6">
<div id="loginfo"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#editinfo-example| &lt; ]]|</td>
<td valign="middle" align="left">|[[#loginfo-example| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#commit-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Loginfo"></div>
==== Loginfo ====
<div id="index-loginfo-_0028admin-file_0029"></div>
<div id="index-Storing-log-messages"></div>
<div id="index-Mailing-log-messages"></div>
<div id="index-Distributing-log-messages"></div>
<div id="index-Log-messages"></div>

<p>The &lsquo;<tt>loginfo</tt>&rsquo; file is used to control where
&lsquo;<samp>cvs commit</samp>&rsquo; 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 <code>$CVSROOT</code>.  If a match is found, then
the remainder of the line is a filter program that
should expect log information on its standard input.
</p>
<p>If the repository name does not match any of the
regular expressions in this file, the &lsquo;<samp>DEFAULT</samp>&rsquo;
line is used, if it is specified.
</p>
<p>All occurrences of the name &lsquo;<samp>ALL</samp>&rsquo; appearing as a
regular expression are used in addition to the first
matching regular expression or &lsquo;<samp>DEFAULT</samp>&rsquo;.
</p>
<p>The first matching regular expression is used.
</p>
<p>See section [[#commit-files|The commit support files]], for a description of the syntax of
the &lsquo;<tt>loginfo</tt>&rsquo; file.
</p>
<p>The user may specify a format string as
part of the filter.  The string is composed of a
&lsquo;<samp>%</samp>&rsquo; followed by a space, or followed by a single
format character, or followed by a set of format
characters surrounded by &lsquo;<samp>{</samp>&rsquo; and &lsquo;<samp>}</samp>&rsquo; as
separators.  The format characters are:
</p>
<dl compact="compact">
<dt> <tt>s</tt></dt>
<dd><p>file name
</p></dd>
<dt> <tt>V</tt></dt>
<dd><p>old version number (pre-checkin)
</p></dd>
<dt> <tt>v</tt></dt>
<dd><p>new version number (post-checkin)
</p></dd>
</dl>

<p>All other characters that appear in a format string
expand to an empty field (commas separating fields are
still provided).
</p>
<p>For example, some valid format strings are &lsquo;<samp>%</samp>&rsquo;,
&lsquo;<samp>%s</samp>&rsquo;, &lsquo;<samp>%{s}</samp>&rsquo;, and &lsquo;<samp>%{sVv}</samp>&rsquo;.
</p>
<p>The output will be a space separated string of tokens enclosed in
quotation marks (<tt>&quot;</tt>).
Any embedded dollar signs (<tt>$</tt>), backticks (<tt>&lsquo;</tt>),
backslashes (<tt>\</tt>), or quotation marks will be preceded
by a backslash (this allows the shell to correctly parse it
as a single string, regardless of the characters it contains).
For backwards compatibility, the first
token will be the repository subdirectory.  The rest of the
tokens will be comma-delimited lists of the information
requested in the format string.  For example, if
&lsquo;<samp>/u/src/master/yoyodyne/tc</samp>&rsquo; is the repository, &lsquo;<samp>%{sVv}</samp>&rsquo;
is the format string, and three files (<tt>ChangeLog</tt>,
<tt>Makefile</tt>, <tt>foo.c</tt>) were modified, the output
might be:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>&quot;yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13&quot;
</nowiki></pre></td></tr></table>

<p>As another example, &lsquo;<samp>%{}</samp>&rsquo; means that only the
name of the repository will be generated.
</p>
<p>Note: when <small>CVS</small> is accessing a remote repository,
&lsquo;<tt>loginfo</tt>&rsquo; will be run on the <em>remote</em>
(i.e., server) side, not the client side (see section [cvs: The Repository#Remote-repositories Remote repositories]).
</p>
<pre class="menu-preformatted"><nowiki></nowiki>&bull;[[#loginfo-example| loginfo example]]::<nowiki>             Loginfo example
</nowiki>&bull;[[#Keeping-a-checked-out-copy| Keeping a checked out copy]]::<nowiki>  Updating a tree on every checkin
</nowiki></pre>
<hr size="6">
<div id="loginfo-example"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#loginfo| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Keeping-a-checked-out-copy| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#loginfo| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Loginfo-example"></div>
===== Loginfo example =====

<p>The following &lsquo;<tt>loginfo</tt>&rsquo; file, together with the
tiny shell-script below, appends all log messages
to the file &lsquo;<tt>$CVSROOT/CVSROOT/commitlog</tt>&rsquo;,
and any commits to the administrative files (inside
the &lsquo;<tt>CVSROOT</tt>&rsquo; directory) are also logged in
&lsquo;<tt>/usr/adm/cvsroot-log</tt>&rsquo;.
Commits to the &lsquo;<tt>prog1</tt>&rsquo; directory are mailed to <tt>ceder</tt>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>ALL             /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER
^CVSROOT        /usr/local/bin/cvs-log /usr/adm/cvsroot-log
^prog1          Mail -s %s ceder
</nowiki></pre></td></tr></table>

<p>The shell-script &lsquo;<tt>/usr/local/bin/cvs-log</tt>&rsquo; looks
like this:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>#!/bin/sh
(echo &quot;------------------------------------------------------&quot;;
 echo -n $2&quot;  &quot;;
 date;
 echo;
 cat) &gt;&gt; $1
</nowiki></pre></td></tr></table>

<hr size="6">
<div id="Keeping-a-checked-out-copy"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#loginfo-example| &lt; ]]|</td>
<td valign="middle" align="left">|[[#rcsinfo| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#loginfo| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Keeping-a-checked-out-copy-1"></div>
===== Keeping a checked out copy =====

<div id="index-Keeping-a-checked-out-copy"></div>
<div id="index-Checked-out-copy_002c-keeping"></div>
<div id="index-Web-pages_002c-maintaining-with-CVS"></div>

<p>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 <small>CVS</small> and want every checkin to cause the files
used by the web server to be updated.
</p>
<p>The way to do this is by having loginfo invoke
<code>cvs update</code>.  Doing so in the naive way will
cause a problem with locks, so the <code>cvs update</code>
must be run in the background.
Here is an example for unix (this should all be on one line):
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>^cyclic-pages		(date; cat; (sleep 2; cd /u/www/local-docs;
 cvs -q update -d) &amp;) &gt;&gt; $CVSROOT/CVSROOT/updatelog 2&gt;&amp;1
</nowiki></pre></td></tr></table>

<p>This will cause checkins to repository directories
starting with <code>cyclic-pages</code> to update the checked
out tree in &lsquo;<tt>/u/www/local-docs</tt>&rsquo;.
</p>
<hr size="6">
<div id="rcsinfo"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Keeping-a-checked-out-copy| &lt; ]]|</td>
<td valign="middle" align="left">|[[#cvsignore| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Administrative-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Rcsinfo"></div>
=== Rcsinfo ===
<div id="index-rcsinfo-_0028admin-file_0029"></div>
<div id="index-Form-for-log-message"></div>
<div id="index-Log-message-template"></div>
<div id="index-Template-for-log-message"></div>

<p>The &lsquo;<tt>rcsinfo</tt>&rsquo; file can be used to specify a form to
edit when filling out the commit log.  The
&lsquo;<tt>rcsinfo</tt>&rsquo; file has a syntax similar to the
&lsquo;<tt>verifymsg</tt>&rsquo;, &lsquo;<tt>commitinfo</tt>&rsquo; and &lsquo;<tt>loginfo</tt>&rsquo;
files.  See section [[#syntax|The common syntax]].  Unlike the other files the second
part is <em>not</em> a command-line template.  Instead,
the part after the regular expression should be a full pathname to
a file containing the log message template.
</p>
<p>If the repository name does not match any of the
regular expressions in this file, the &lsquo;<samp>DEFAULT</samp>&rsquo;
line is used, if it is specified.
</p>
<p>All occurrences of the name &lsquo;<samp>ALL</samp>&rsquo; appearing as a
regular expression are used in addition to the first
matching regular expression or &lsquo;<samp>DEFAULT</samp>&rsquo;.
</p>
<p>The log message template will be used as a default log
message.  If you specify a log message with &lsquo;<samp>cvs
commit -m <var>message</var></samp>&rsquo; or &lsquo;<samp>cvs commit -f
<var>file</var></samp>&rsquo; that log message will override the
template.
</p>
<p>See section [[#verifymsg|Verifying log messages]], for an example &lsquo;<tt>rcsinfo</tt>&rsquo;
file.
</p>
<p>When <small>CVS</small> is accessing a remote repository,
the contents of &lsquo;<tt>rcsinfo</tt>&rsquo; at the time a directory
is first checked out will specify a template. This
template will be updated on all &lsquo;<samp>cvs update</samp>&rsquo;
commands. It will also be added to new directories
added with a &lsquo;<samp>cvs add new-directry</samp>&rsquo; command.
In versions of <small>CVS</small> prior to version 1.12, the
&lsquo;<tt>CVS/Template</tt>&rsquo; file was not updated. If the
<small>CVS</small> server is at version 1.12 or higher an older
client may be used and the &lsquo;<tt>CVS/Template</tt>&rsquo; will
be updated from the server.
</p>
<hr size="6">
<div id="cvsignore"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#rcsinfo| &lt; ]]|</td>
<td valign="middle" align="left">|[[#checkoutlist| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Administrative-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Ignoring-files-via-cvsignore"></div>
=== Ignoring files via cvsignore ===
<div id="index-cvsignore-_0028admin-file_0029_002c-global"></div>
<div id="index-Global-cvsignore"></div>
<div id="index-Ignoring-files"></div>

<p>There are certain file names that frequently occur
inside your working copy, but that you don&rsquo;t want to
put under <small>CVS</small> control.  Examples are all the object
files that you get while you compile your sources.
Normally, when you run &lsquo;<samp>cvs update</samp>&rsquo;, it prints a
line for each file it encounters that it doesn&rsquo;t know
about (see section [cvs: Guide to CVS commands#update-output update output]).
</p>
<p><small>CVS</small> has a list of files (or sh(1) file name patterns)
that it should ignore while running <code>update</code>,
<code>import</code> and <code>release</code>.
This list is constructed in the following way.
</p>
<ul>
<li>
The list is initialized to include certain file name
patterns: names associated with <small>CVS</small>
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:

<div id="index-Ignored-files"></div>
<div id="index-Automatically-ignored-files"></div>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>    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
</nowiki></pre></td></tr></table>

</li><li>
The per-repository list in
&lsquo;<tt>$CVSROOT/CVSROOT/cvsignore</tt>&rsquo; is appended to
the list, if that file exists.

</li><li>
The per-user list in &lsquo;<tt>.cvsignore</tt>&rsquo; in your home
directory is appended to the list, if it exists.

</li><li>
Any entries in the environment variable
<code>$CVSIGNORE</code> is appended to the list.

</li><li>
Any &lsquo;<samp>-I</samp>&rsquo; options given to <small>CVS</small> is appended.

</li><li>
As <small>CVS</small> traverses through your directories, the contents
of any &lsquo;<tt>.cvsignore</tt>&rsquo; will be appended to the list.
The patterns found in &lsquo;<tt>.cvsignore</tt>&rsquo; are only valid
for the directory that contains them, not for
any sub-directories.
</li></ul>

<p>In any of the 5 places listed above, a single
exclamation mark (&lsquo;<samp>!</samp>&rsquo;) clears the ignore list.
This can be used if you want to store any file which
normally is ignored by <small>CVS</small>.
</p>
<p>Specifying &lsquo;<samp>-I !</samp>&rsquo; to <code>cvs import</code> 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 &lsquo;<tt>.cvsignore</tt>&rsquo; files, then
the patterns from those files will be processed even if
&lsquo;<samp>-I !</samp>&rsquo; is specified.  The only workaround is to
remove the &lsquo;<tt>.cvsignore</tt>&rsquo; files in order to do the
import.  Because this is awkward, in the future
&lsquo;<samp>-I !</samp>&rsquo; might be modified to override
&lsquo;<tt>.cvsignore</tt>&rsquo; files in each directory.
</p>
<p>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 &lsquo;<tt>foo?bar</tt>&rsquo; to match a file
named &lsquo;<tt>foo bar</tt>&rsquo; (it also matches &lsquo;<tt>fooxbar</tt>&rsquo;
and the like).  Also note that there is currently no
way to specify comments.
</p>
<hr size="6">
<div id="checkoutlist"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#cvsignore| &lt; ]]|</td>
<td valign="middle" align="left">|[[#history-file| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Administrative-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="The-checkoutlist-file"></div>
=== The checkoutlist file ===
<div id="index-checkoutlist"></div>

<p>It may be helpful to use <small>CVS</small> to maintain your own
files in the &lsquo;<tt>CVSROOT</tt>&rsquo; directory.  For example,
suppose that you have a script &lsquo;<tt>logcommit.pl</tt>&rsquo;
which you run by including the following line in the
&lsquo;<tt>commitinfo</tt>&rsquo; administrative file:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>ALL   $CVSROOT/CVSROOT/logcommit.pl
</nowiki></pre></td></tr></table>

<p>To maintain &lsquo;<tt>logcommit.pl</tt>&rsquo; with <small>CVS</small> you would
add the following line to the &lsquo;<tt>checkoutlist</tt>&rsquo;
administrative file:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>logcommit.pl
</nowiki></pre></td></tr></table>

<p>The format of &lsquo;<tt>checkoutlist</tt>&rsquo; is one line for each
file that you want to maintain using <small>CVS</small>, giving
the name of the file.
</p>
<p>After setting up &lsquo;<tt>checkoutlist</tt>&rsquo; in this fashion,
the files listed there will function just like
<small>CVS</small>&rsquo;s built-in administrative files.  For example,
when checking in one of the files you should get a
message such as:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>cvs commit: Rebuilding administrative file database
</nowiki></pre></td></tr></table>

<p>and the checked out copy in the &lsquo;<tt>CVSROOT</tt>&rsquo;
directory should be updated.
</p>
<p>Note that listing &lsquo;<tt>passwd</tt>&rsquo; (see section [cvs: The Repository#Password-authentication-server Setting up the server for password authentication]) in &lsquo;<tt>checkoutlist</tt>&rsquo; is not
recommended for security reasons.
</p>
<p>For information about keeping a checkout out copy in a
more general context than the one provided by
&lsquo;<tt>checkoutlist</tt>&rsquo;, see [[#Keeping-a-checked-out-copy|Keeping a checked out copy]].
</p>
<hr size="6">
<div id="history-file"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#checkoutlist| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Variables| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Administrative-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="The-history-file"></div>
=== The history file ===
<div id="index-History-file"></div>
<div id="index-Log-information_002c-saving"></div>

<p>The file &lsquo;<tt>$CVSROOT/CVSROOT/history</tt>&rsquo; is used
to log information for the <code>history</code> command
(see section [cvs: Guide to CVS commands#history history&mdash;Show status of files and users]).  This file must be created to turn
on logging.  This is done automatically if the
<code>cvs init</code> command is used to set up the
repository (see section [cvs: The Repository#Creating-a-repository Creating a repository]).
</p>
<p>The file format of the &lsquo;<tt>history</tt>&rsquo; file is
documented only in comments in the <small>CVS</small> source
code, but generally programs should use the <code>cvs
history</code> command to access it anyway, in case the
format changes with future releases of <small>CVS</small>.
</p>
<hr size="6">
<div id="Variables"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#history-file| &lt; ]]|</td>
<td valign="middle" align="left">|[[#config| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Administrative-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Expansions-in-administrative-files"></div>
=== Expansions in administrative files ===
<div id="index-Internal-variables"></div>
<div id="index-Variables"></div>

<p>Sometimes in writing an administrative file, you might
want the file to be able to know various things based
on environment <small>CVS</small> is running in.  There are
several mechanisms to do that.
</p>
<p>To find the home directory of the user running <small>CVS</small>
(from the <code>HOME</code> environment variable), use
&lsquo;<samp>~</samp>&rsquo; followed by &lsquo;<samp>/</samp>&rsquo; or the end of the line.
Likewise for the home directory of <var>user</var>, use
&lsquo;<samp>~<var>user</var></samp>&rsquo;.  These variables are expanded on
the server machine, and don&rsquo;t get any reasonable
expansion if pserver (see section [cvs: The Repository#Password-authenticated 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 <small>CVS</small>.
</p>
<p>One may want to know about various pieces of
information internal to <small>CVS</small>.  A <small>CVS</small> internal
variable has the syntax <code>${<var>variable</var>}</code>,
where <var>variable</var> starts with a letter and consists
of alphanumeric characters and &lsquo;<samp>_</samp>&rsquo;.  If the
character following <var>variable</var> is a
non-alphanumeric character other than &lsquo;<samp>_</samp>&rsquo;, the
&lsquo;<samp>{</samp>&rsquo; and &lsquo;<samp>}</samp>&rsquo; can be omitted.  The <small>CVS</small>
internal variables are:
</p>
<dl compact="compact">
<dt> <code>CVSROOT</code></dt>
<dd><div id="index-CVSROOT_002c-internal-variable"></div>
<p>This is the absolute path to the current <small>CVS</small> root directory.
See section [cvs: The Repository#Repository The 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.
</p>
</dd>
<dt> <code>RCSBIN</code></dt>
<dd><div id="index-RCSBIN_002c-internal-variable"></div>
<p>In <small>CVS</small> 1.9.18 and older, this specified the
directory where <small>CVS</small> was looking for <small>RCS</small>
programs.  Because <small>CVS</small> no longer runs <small>RCS</small>
programs, specifying this internal variable is now an
error.
</p>
</dd>
<dt> <code>CVSEDITOR</code></dt>
<dd><div id="index-CVSEDITOR_002c-internal-variable"></div>
</dd>
<dt> <code>EDITOR</code></dt>
<dd><div id="index-EDITOR_002c-internal-variable"></div>
</dd>
<dt> <code>VISUAL</code></dt>
<dd><div id="index-VISUAL_002c-internal-variable"></div>
<p>These all expand to the same value, which is the editor
that <small>CVS</small> is using.  See section [cvs: Guide to CVS commands#Global-options Global options], for how
to specify this.
</p>
</dd>
<dt> <code>USER</code></dt>
<dd><div id="index-USER_002c-internal-variable"></div>
<p>Username of the user running <small>CVS</small> (on the <small>CVS</small>
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 (see section [cvs: The Repository#Password-authentication-server Setting up the server for password authentication]).
Do not confuse this with the environment variable of the same name.
</p></dd>
</dl>

<p>If you want to pass a value to the administrative files
which the user who is running <small>CVS</small> can specify,
use a user variable.
<div id="index-User-variables"></div>
To expand a user variable, the
administrative file contains
<code>${=<var>variable</var>}</code>.  To set a user variable,
specify the global option &lsquo;<samp>-s</samp>&rsquo; to <small>CVS</small>, with
argument <code><var>variable</var>=<var>value</var></code>.  It may be
particularly useful to specify this option via
&lsquo;<tt>.cvsrc</tt>&rsquo; (see section [cvs: Guide to CVS commands#g_t_007e_002f_002ecvsrc Default options and the ~/.cvsrc file]).
</p>
<p>For example, if you want the administrative file to
refer to a test directory you might create a user
variable <code>TESTDIR</code>.  Then if <small>CVS</small> is invoked
as
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>cvs -s TESTDIR=/work/local/tests
</nowiki></pre></td></tr></table>

<p>and the
administrative file contains <code>sh
${=TESTDIR}/runtests</code>, then that string is expanded
to <code>sh /work/local/tests/runtests</code>.
</p>
<p>All other strings containing &lsquo;<samp>$</samp>&rsquo; are reserved;
there is no way to quote a &lsquo;<samp>$</samp>&rsquo; character so that
&lsquo;<samp>$</samp>&rsquo; represents itself.
</p>
<p>Environment variables passed to administrative files are:
</p>
<dl compact="compact">
<dd><div id="index-environment-variables_002c-passed-to-administrative-files"></div>

</dd>
<dt> <code>CVS_USER</code></dt>
<dd><div id="index-CVS_005fUSER_002c-environment-variable"></div>
<p>The <small>CVS</small>-specific username provided by the user, if it
can be provided (currently just for the pserver access
method), and to the empty string otherwise.  (<code>CVS_USER</code>
and <code>USER</code> may differ when &lsquo;<tt>$CVSROOT/CVSROOT/passwd</tt>&rsquo;
is used to map <small>CVS</small> usernames to system usernames.)
</p>
</dd>
<dt> <code>LOGNAME</code></dt>
<dd><div id="index-LOGNAME_002c-environment-variable"></div>
<p>The username of the system user.
</p>
</dd>
<dt> <code>USER</code></dt>
<dd><div id="index-USER_002c-environment-variable"></div>
<p>Same as <code>LOGNAME</code>.
Do not confuse this with the internal variable of the same name.
</p></dd>
</dl>

<hr size="6">
<div id="config"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Variables| &lt; ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Administrative-files| Up ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="The-CVSROOT_002fconfig-configuration-file"></div>
=== The CVSROOT/config configuration file ===

<div id="index-config_002c-in-CVSROOT"></div>
<div id="index-CVSROOT_002fconfig"></div>

<p>The administrative file &lsquo;<tt>config</tt>&rsquo; contains various
miscellaneous settings which affect the behavior of
<small>CVS</small>.  The syntax is slightly different from the
other administrative files.  Variables are not
expanded.  Lines which start with &lsquo;<samp>#</samp>&rsquo; are
considered comments.
Other lines consist of a keyword, &lsquo;<samp>=</samp>&rsquo;, and a
value.  Note that this syntax is very strict.
Extraneous spaces or tabs are not permitted.
</p>
<p>Currently defined keywords are:
</p>
<dl compact="compact">
<dd><div id="index-RCSBIN_002c-in-CVSROOT_002fconfig"></div>
</dd>
<dt> <code>RCSBIN=<var>bindir</var></code></dt>
<dd><p>For <small>CVS</small> 1.9.12 through 1.9.18, this setting told
<small>CVS</small> to look for <small>RCS</small> programs in the
<var>bindir</var> directory.  Current versions of <small>CVS</small>
do not run <small>RCS</small> programs; for compatibility this
setting is accepted, but it does nothing.
</p>
<div id="index-SystemAuth_002c-in-CVSROOT_002fconfig"></div>
</dd>
<dt> <code>SystemAuth=<var>value</var></code></dt>
<dd><p>If <var>value</var> is &lsquo;<samp>yes</samp>&rsquo;, then pserver should check
for users in the system&rsquo;s user database if not found in
&lsquo;<tt>CVSROOT/passwd</tt>&rsquo;.  If it is &lsquo;<samp>no</samp>&rsquo;, then all
pserver users must exist in &lsquo;<tt>CVSROOT/passwd</tt>&rsquo;.
The default is &lsquo;<samp>yes</samp>&rsquo;.  For more on pserver, see
[cvs: The Repository#Password-authenticated Direct connection with password authentication].
</p>

<div id="index-TopLevelAdmin_002c-in-CVSROOT_002fconfig"></div>
</dd>
<dt> <code>TopLevelAdmin=<var>value</var></code></dt>
<dd><p>Modify the &lsquo;<samp>checkout</samp>&rsquo; command to create a
&lsquo;<samp>CVS</samp>&rsquo; directory at the top level of the new
working directory, in addition to &lsquo;<samp>CVS</samp>&rsquo;
directories created within checked-out directories.
The default value is &lsquo;<samp>no</samp>&rsquo;.
</p>
<p>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 &lsquo;<tt>CVS</tt>&rsquo; directory created there
will mean you don&rsquo;t have to specify <code>CVSROOT</code> for
each command.  It also provides a place for the
&lsquo;<tt>CVS/Template</tt>&rsquo; file (see section [cvs: The Repository#Working-directory-storage How data is stored in the working directory]).
</p>
<div id="index-LockDir_002c-in-CVSROOT_002fconfig"></div>
</dd>
<dt> <code>LockDir=<var>directory</var></code></dt>
<dd><p>Put <small>CVS</small> lock files in <var>directory</var> 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 <var>directory</var>, 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 <var>directory</var>, but
<small>CVS</small> will create subdirectories of <var>directory</var> as it
needs them.  For information on <small>CVS</small> locks, see
[cvs: Multiple developers#Concurrency Several developers simultaneously attempting to run CVS].
</p>
<p>Before enabling the LockDir option, make sure that you
have tracked down and removed any copies of <small>CVS</small> 1.9 or
older.  Such versions neither support LockDir, nor will
give an error indicating that they don&rsquo;t support it.
The result, if this is allowed to happen, is that some
<small>CVS</small> users will put the locks one place, and others will
put them another place, and therefore the repository
could become corrupted.  <small>CVS</small> 1.10 does not support
LockDir but it will print a warning if run on a
repository with LockDir enabled.
</p>
<div id="index-LogHistory_002c-in-CVSROOT_002fconfig"></div>
</dd>
<dt> <code>LogHistory=<var>value</var></code></dt>
<dd><p>Control what is logged to the &lsquo;<tt>CVSROOT/history</tt>&rsquo; file (see section [cvs: Guide to CVS commands#history history&mdash;Show status of files and users]).
Default of &lsquo;<samp>TOEFWUCGMAR</samp>&rsquo; (or simply &lsquo;<samp>all</samp>&rsquo;) will log
all transactions.  Any subset of the default is
legal.  (For example, to only log transactions that modify the
&lsquo;<tt>*,v</tt>&rsquo; files, use &lsquo;<samp>LogHistory=TMAR</samp>&rsquo;.)
</p>
<div id="index-RereadLogAfterVerify_002c-in-CVSROOT_002fconfig"></div>
<div id="index-verifymsg_002c-changing-the-log-message-1"></div>
</dd>
<dt> <code>RereadLogAfterVerify=<var>value</var></code></dt>
<dd><p>Modify the &lsquo;<samp>commit</samp>&rsquo; command such that CVS will reread the
log message after running the program specified by &lsquo;<tt>verifymsg</tt>&rsquo;.
<var>value</var> may be one of &lsquo;<samp>yes</samp>&rsquo; or &lsquo;<samp>always</samp>&rsquo;, indicating that
the log message should always be reread; &lsquo;<samp>no</samp>&rsquo;
or &lsquo;<samp>never</samp>&rsquo;, indicating that it should never be
reread; or <var>value</var> may be &lsquo;<samp>stat</samp>&rsquo;, indicating
that the file should be checked with the filesystem
&lsquo;<samp>stat()</samp>&rsquo; function to see if it has changed (see warning below)
before rereading.  The default value is &lsquo;<samp>always</samp>&rsquo;.
</p>
<p><strong>Note: the &lsquo;stat&rsquo; 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</strong>
</p>
<p>See section [[#verifymsg|Verifying log messages]], for more information on how verifymsg
may be used.
</p>
<div id="index-UserAdminOptions_002c-in-CVSROOT_002fconfig-1"></div>
</dd>
<dt> <code>UserAdminOptions=<var>value</var></code></dt>
<dd><p>Control what options will be allowed with the <code>cvs admin</code>
command (see section [cvs: Guide to CVS commands#admin admin&mdash;Administration]) for users not in the <code>cvsadmin</code> group.
The <var>value</var> string is a list of single character options
which should be allowed.  If a user who is not a member of the
<code>cvsadmin</code> group tries to execute any <code>cvs admin</code>
option which is not listed they will will receive an error message
reporting that the option is restricted.
</p>
<p>If no <code>cvsadmin</code> group exists on the server, <small>CVS</small> will
ignore the <code>UserAdminOptions</code> keyword (see section [cvs: Guide to CVS commands#admin admin&mdash;Administration]).
</p>
<p>When not specified, <code>UserAdminOptions</code> defaults to
&lsquo;<samp>k</samp>&rsquo;.  In other words, it defaults to allowing
users outside of the <code>cvsadmin</code> group to use the
<code>cvs admin</code> command only to change the default keyword
expansion mode for files.
</p>
<p>As an example, to restrict users not in the <code>cvsadmin</code>
group to using <code>cvs admin</code> to change the default keyword
substitution mode, lock revisions, unlock revisions, and
replace the log message, use &lsquo;<samp>UserAdminOptions=klum</samp>&rsquo;.
</p></dd>
</dl>

<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Administrative-files| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[cvs: All environment variables which affect CVS#Environment-variables  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
This document was generated by <em>a tester</em> on <em>a sunny day</em> using [http://www.nongnu.org/texi2html/ <em>texi2html</em>].
