path: root/gnu/usr.bin/cvs/man/cvs.5

.TH cvs 5 "12 February 1992"
.\" Full space in nroff; half space in troff
.de SP
.if n .sp
.if t .sp .5
..
.SH NAME
cvs \- Concurrent Versions System support files
.SH SYNOPSIS
.hy 0
.na
.TP
.B $CVSROOT/CVSROOT/modules,v
.TP
.B $CVSROOT/CVSROOT/commitinfo,v
.TP
.B $CVSROOT/CVSROOT/loginfo,v
.TP
.B $CVSROOT/CVSROOT/rcsinfo,v
.TP
.B $CVSROOT/CVSROOT/editinfo,v
.TP
.B $CVSROOT/CVSROOT/cvsignore,v
.TP
.B $CVSROOT/CVSROOT/history
.ad b
.hy 1
.SH DESCRIPTION
.B cvs
is a system for providing source control to hierarchical collections
of source directories.  Commands and procedures for using \fBcvs\fP
are described in
.BR cvs ( 1 ).
.SP
.B cvs
manages \fIsource repositories\fP, the directories containing master
copies of the revision-controlled files, by copying particular
revisions of the files to (and modifications back from) developers'
private \fIworking directories\fP.  In terms of file structure, each
individual source repository is an immediate subdirectory of
\fB$CVSROOT\fP.
.SP
The files described here are supporting files; they do not have to
exist for \fBcvs\fP to operate, but they allow you to make \fBcvs\fP
operation more flexible.
.SP
The
.BR cvsinit ( 1 )
shell script included at the top-level of the
.B cvs
distribution can be used to setup an initial
.B $CVSROOT/CVSROOT
area, if you don't have one already.
.SP
You can use the `\|modules\|' file to define symbolic names for
collections of source maintained with \fBcvs\fP.  If there is no
`\|modules\|' file, developers must specify complete path names
(absolute, or relative to \fB$CVSROOT\fP) for the files they wish to
manage with \fBcvs\fP commands.
.SP
You can use the `\|commitinfo\|' file to define programs to execute
whenever `\|\fBcvs commit\fP\|' 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.
Some uses for this check might be to turn off a portion (or all) of the
source repository from a particular person or group.
Or, perhaps, to verify that the changed files conform to the site's
standards for coding practice.
.SP
You can use the `\|loginfo\|' file to define programs to execute after
any
.BR commit ,
which writes a log entry for changes in the repository.
These logging programs might be used to append the log message to a file.
Or send the log message through electronic mail to a group of developers.
Or, perhaps, post the log message to a particular newsgroup.
.SP
You can use the `\|rcsinfo\|' file to define forms for log messages.
.SP
You can use the `\|editinfo\|' file to define a program to execute for
editing/validating `\|\fBcvs commit\fP\|' log entries.
This is most useful when used with a `\|rcsinfo\|' forms specification, as
it can verify that the proper fields of the form have been filled in by the
user committing the change.
.SP
You can use the `\|cvsignore\|' file to specify the default list of
files to ignore during \fBupdate\fP.
.SP
You can use the `\|history\|' file to record the \fBcvs\fP commands
that affect the repository.
The creation of this file enables history logging.
.SH FILES
.TP
.B modules
The `\|modules\|' file records your definitions of names for
collections of source code.  \fBcvs\fP will use these definitions if
you create a file with the right format in
`\|\fB$CVSROOT/CVSROOT/modules,v\fP\|'.  
The
.BR mkmodules ( 1 )
command should be run whenever the modules file changes, so that the
appropriate files can be generated (depending on how you have configured
.B cvs
operation).
.SP
To allow convenient editing of the `\|modules\|' file itself, the file should
include an entry like the following (where \fIlocalbin\fP represents the
directory where your site installs programs like
.BR mkmodules ( 1 )):
.SP
.nf
\&\fBmodules    \-i /\fP\fIlocalbin\fP\fB/mkmodules CVSROOT modules\fP
.fi
.SP
This defines the name `\|\fBmodules\fP\|' as the module name for the
file itself, so that you can use
.SP
.in +1i
.ft B
.nf
example% cvs checkout modules
.fi
.ft P
.in -1i
.SP
to get an editable copy of the file.  You should define similar module
entries for the other configuration files described here (except
\&`\|history\|').
The
.BR cvsinit ( 1 )
script will setup a smilar `\|modules\|' file for you automatically.
.SP
The `\|modules\|' file may contain blank lines and comments (lines
beginning with `\|\fB#\fP\|') as well as module definitions.
Long lines can be continued on the next line by specifying a backslash
(``\e'') as the last character on the line.
.SP
A \fImodule definition\fP is a single line of the `\|modules\|' file,
in either of two formats.  In both cases, \fImname\fP represents the
symbolic module name, and the remainder of the line is its definition.
.SP
\fImname\fP \fB\-a\fP \fIaliases\fP\|.\|.\|.
.br
This represents the simplest way of defining a module \fImname\fP.
The `\|\fB\-a\fP\|' flags the definition as a simple alias: \fBcvs\fP
will treat any use of \fImname\fP (as a command argument) as if the list
of names \fIaliases\fP had been specified instead.  \fIaliases\fP may
contain either other module names or paths.  When you use paths in
\fIaliases\fP, `\|\fBcvs checkout\fP\|' creates all intermediate
directories in the working directory, just as if the path had been
specified explicitly in the \fBcvs\fP arguments.
.SP
.nf
\fImname\fP [ \fIoptions\fP ] \fIdir\fP [ \fIfiles\fP\|.\|.\|. ] [ \fB&\fP\fImodule\fP\|.\|.\|. ]
.fi
.SP
In the simplest case, this form of module definition reduces to
`\|\fImname dir\fP\|'.  This defines all the files in directory
\fIdir\fP as module \fImname\fP.  \fIdir\fP is a relative path (from
\fB$CVSROOT\fP) to a directory of source in one of the source
repositories.  In this case, on \fBcheckout\fP, a single directory
called \fImname\fP is created as a working directory; no intermediate
directory levels are used by default, even if \fIdir\fP was a path
involving several directory levels.
.SP
By explicitly specifying \fIfiles\fP in the module definition after
\fIdir\fP, you can select particular files from directory
\fIdir\fP.  The sample definition for \fBmodules\fP is an example of
a module defined with a single file from a particular directory.  Here
is another example:
.SP
.nf
.ft B
m4test  unsupported/gnu/m4 foreach.m4 forloop.m4
.ft P
.fi
.SP
With this definition, executing `\|\fBcvs checkout m4test\fP\|'
will create a single working directory `\|m4test\|' containing the two
files listed, which both come from a common directory several levels
deep in the \fBcvs\fP source repository.
.SP
A module definition can refer to other modules by including
`\|\fB&\fP\fImodule\fP\|' in its definition.  \fBcheckout\fP creates
a subdirectory for each such \fImodule\fP, in your working directory.
.br
.I
New in \fBcvs\fP 1.3;
avoid this feature if sharing module definitions with older versions
of \fBcvs\fP.
.SP
Finally, you can use one or more of the following \fIoptions\fP in
module definitions:
.SP
\&`\|\fB\-d\fP \fIname\fP\|', to name the working directory something
other than the module name.
.br
.I
New in \fBcvs\fP 1.3;
avoid this feature if sharing module definitions with older versions
of \fBcvs\fP.
.SP
\&`\|\fB\-i\fP \fIprog\fP\|' allows you to specify a program \fIprog\fP
to run whenever files in a module are committed.  \fIprog\fP runs with a
single argument, the full pathname of the affected directory in a
source repository.   The `\|commitinfo\|', `\|loginfo\|', and
`\|editinfo\|' files provide other ways to call a program on \fBcommit\fP.
.SP
`\|\fB\-o\fP \fIprog\fP\|' allows you to specify a program \fIprog\fP
to run whenever files in a module are checked out.  \fIprog\fP runs
with a single argument, the module name.
.SP
`\|\fB\-t\fP \fIprog\fP\|' allows you to specify a program \fIprog\fP
to run whenever files in a module are tagged.  \fIprog\fP runs with two
arguments:  the module name and the symbolic tag specified to \fBrtag\fP.
.SP
`\|\fB\-u\fP \fIprog\fP\|' allows you to specify a program \fIprog\fP
to run whenever `\|\fBcvs update\fP\|' is executed from the top-level
directory of the checked-out module.  \fIprog\fP runs with a
single argument, the full path to the source repository for this module.
.TP
\&\fBcommitinfo\fP, \fBloginfo\fP, \fBrcsinfo\fP, \fBeditinfo\fP
These files all specify programs to call at different points in the
`\|\fBcvs commit\fP\|' process.  They have a common structure.
Each line is a pair of fields: a regular expression, separated by
whitespace from a filename or command-line template.
Whenever one of the regular expression matches a directory name in the
repository, the rest of the line is used.
If the line begins with a \fB#\fP character, the entire line is considered
a comment and is ignored.
Whitespace between the fields is also ignored.
.SP
For `\|loginfo\|', the rest of the
line is a command-line template to execute.
The templates can include not only
a program name, but whatever list of arguments you wish.  If you write
`\|\fB%s\fP\|' somewhere on the argument list, \fBcvs\fP supplies, at
that point, the list of files affected by the \fBcommit\fP. 
The first entry in the list is the relative path within the source
repository where the change is being made.
The remaining arguments list the files that are being modified, added, or
removed by this \fBcommit\fP invocation.
.SP
For `\|commitinfo\|', the rest of the line is a command-line template to
execute.
The template can include not only a program name, but whatever
list of arguments you wish.
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).
.SP
For `\|rcsinfo\|', the rest of the line is the full path to a file that
should be loaded into the log message template.
.SP
For `\|editinfo\|', the rest of the line is a command-line template to
execute.
The template can include not only a program name, but whatever
list of arguments you wish.
The full path to the current log message template file is appended to the
template.
.SP
You can use one of two special strings instead of a regular
expression: `\|\fBALL\fP\|' specifies a command line template that
must always be executed, and `\|\fBDEFAULT\fP\|' specifies a command
line template to use if no regular expression is a match.
.SP
The `\|commitinfo\|' file contains commands to execute \fIbefore\fP any
other \fBcommit\fP activity, to allow you to check any conditions that
must be satisfied before \fBcommit\fP can proceed.  The rest of the
\fBcommit\fP will execute only if all selected commands from this file
exit with exit status \fB0\fP.
.SP
The `\|rcsinfo\|' file allows you to specify \fIlog templates\fP for
the \fBcommit\fP logging session; you can use this to provide a form
to edit when filling out the \fBcommit\fP log.  The field after the
regular expression, in this file, contains filenames (of files
containing the logging forms) rather than command templates.
.SP
The `\|editinfo\|' file allows you to execute a script \fIbefore the
commit starts\fP, but after the log information is recorded.  These
"edit" scripts can verify information recorded in the log file.  If
the edit script exits wth a non-zero exit status, the commit is aborted.
.SP
The `\|loginfo\|' file contains commands to execute \fIat the end\fP
of a commit.  The text specified as a commit log message is piped
through the command; typical uses include sending mail, filing an
article in a newsgroup, or appending to a central file.
.TP
\&\fBcvsignore\fP, \fB.cvsignore\fP
The default list of files (or
.BR sh ( 1 )
file name patterns) to ignore during `\|\fBcvs update\fP\|'.
At startup time, \fBcvs\fP loads the compiled in default list of file name
patterns (see
.BR cvs ( 1 )).
Then the per-repository list included in \fB$CVSROOT/CVSROOT/cvsignore\fP
is loaded, if it exists.
Then the per-user list is loaded from `\|$HOME/.cvsignore\|'.
Finally, as \fBcvs\fP traverses through your directories, it will load any
per-directory `\|.cvsignore\|' files whenever it finds one.
These per-directory files are only valid for exactly the directory that
contains them, not for any sub-directories.
.TP
.B history
Create this file in \fB$CVSROOT/CVSROOT\fP to enable history logging
(see the description of `\|\fBcvs history\fP\|').
.SH "SEE ALSO"
.BR cvs ( 1 ),
.BR mkmodules ( 1 ).
.SH COPYING
Copyright \(co 1992 Cygnus Support, Brian Berliner, and Jeff Polk
.PP
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
.PP
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
.PP
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be included in
translations approved by the Free Software Foundation instead of in
the original English.