also stop shipping cvshelp.man (gah, mkmodules!)
[alioth/cvs.git] / man / cvs.5
1 .TH cvs 5 "12 February 1992"
2 .\" Full space in nroff; half space in troff
3 .de SP
4 .if n .sp
5 .if t .sp .5
6 ..
7 .SH NAME
8 cvs \- Concurrent Versions System support files
9 .SH NOTE
10 This documentation may no longer be up to date.  Please consult the Cederqvist
11 (CVS Manual) as specified in
12 .BR cvs ( 1 ).
13
14 .SH SYNOPSIS
15 .hy 0
16 .na
17 .TP
18 .B $CVSROOT/CVSROOT/commitinfo,v
19 .TP
20 .B $CVSROOT/CVSROOT/cvsignore,v
21 .TP
22 .B $CVSROOT/CVSROOT/cvswrappers,v
23 .TP
24 .B $CVSROOT/CVSROOT/editinfo,v
25 .TP
26 .B $CVSROOT/CVSROOT/history
27 .TP
28 .B $CVSROOT/CVSROOT/loginfo,v
29 .TP
30 .B $CVSROOT/CVSROOT/modules,v
31 .TP
32 .B $CVSROOT/CVSROOT/rcsinfo,v
33 .TP
34 .B $CVSROOT/CVSROOT/taginfo,v
35 .ad b
36 .hy 1
37 .SH DESCRIPTION
38 .B cvs
39 is a system for providing source control to hierarchical collections
40 of source directories.  Commands and procedures for using \fBcvs\fP
41 are described in
42 .BR cvs ( 1 ).
43 .SP
44 .B cvs
45 manages \fIsource repositories\fP, the directories containing master
46 copies of the revision-controlled files, by copying particular
47 revisions of the files to (and modifications back from) developers'
48 private \fIworking directories\fP.  In terms of file structure, each
49 individual source repository is an immediate subdirectory of
50 \fB$CVSROOT\fP.
51 .SP
52 The files described here are supporting files; they do not have to
53 exist for \fBcvs\fP to operate, but they allow you to make \fBcvs\fP
54 operation more flexible.
55 .SP
56 You can use the `\|modules\|' file to define symbolic names for
57 collections of source maintained with \fBcvs\fP.  If there is no
58 `\|modules\|' file, developers must specify complete path names
59 (absolute, or relative to \fB$CVSROOT\fP) for the files they wish to
60 manage with \fBcvs\fP commands.
61 .SP
62 You can use the `\|commitinfo\|' file to define programs to execute
63 whenever `\|\fBcvs commit\fP\|' is about to execute.
64 These programs are used for ``pre-commit'' checking to verify that the
65 modified, added, and removed files are really ready to be committed.
66 Some uses for this check might be to turn off a portion (or all) of the
67 source repository from a particular person or group.
68 Or, perhaps, to verify that the changed files conform to the site's
69 standards for coding practice.
70 .SP
71 You can use the `\|cvswrappers\|' file to record
72 .B cvs
73 wrapper commands to be used when checking files into and out of the
74 repository.  Wrappers allow the file or directory to be processed
75 on the way in and out of CVS.  The intended uses are many, one
76 possible use would be to reformat a C file before the file is checked
77 in, so all of the code in the repository looks the same.
78 .SP
79 You can use the `\|loginfo\|' file to define programs to execute after
80 any
81 .BR commit ,
82 which writes a log entry for changes in the repository.
83 These logging programs might be used to append the log message to a file.
84 Or send the log message through electronic mail to a group of developers.
85 Or, perhaps, post the log message to a particular newsgroup.
86 .SP
87 You can use the `\|taginfo\|' file to define programs to execute after
88 any
89 .BR tag or rtag
90 operation.  These programs might be used to append a message to a file
91 listing the new tag name and the programmer who created it, or send mail
92 to a group of developers, or, perhaps, post a message to a particular
93 newsgroup.
94 .SP
95 You can use the `\|rcsinfo\|' file to define forms for log messages.
96 .SP
97 You can use the `\|editinfo\|' file to define a program to execute for
98 editing/validating `\|\fBcvs commit\fP\|' log entries.
99 This is most useful when used with a `\|rcsinfo\|' forms specification, as
100 it can verify that the proper fields of the form have been filled in by the
101 user committing the change.
102 .SP
103 You can use the `\|cvsignore\|' file to specify the default list of
104 files to ignore during \fBupdate\fP.
105 .SP
106 You can use the `\|history\|' file to record the \fBcvs\fP commands
107 that affect the repository.
108 The creation of this file enables history logging.
109 .SH FILES
110 .TP
111 .B modules
112 The `\|modules\|' file records your definitions of names for
113 collections of source code.  \fBcvs\fP will use these definitions if
114 you use \fBcvs\fP to check in a file with the right format to
115 `\|\fB$CVSROOT/CVSROOT/modules,v\fP\|'.  
116 .SP
117 The `\|modules\|' file may contain blank lines and comments (lines
118 beginning with `\|\fB#\fP\|') as well as module definitions.
119 Long lines can be continued on the next line by specifying a backslash
120 (``\e'') as the last character on the line.
121 .SP
122 A \fImodule definition\fP is a single line of the `\|modules\|' file,
123 in either of two formats.  In both cases, \fImname\fP represents the
124 symbolic module name, and the remainder of the line is its definition.
125 .SP
126 \fImname\fP \fB\-a\fP \fIaliases\fP\|.\|.\|.
127 .br
128 This represents the simplest way of defining a module \fImname\fP.
129 The `\|\fB\-a\fP\|' flags the definition as a simple alias: \fBcvs\fP
130 will treat any use of \fImname\fP (as a command argument) as if the list
131 of names \fIaliases\fP had been specified instead.  \fIaliases\fP may
132 contain either other module names or paths.  When you use paths in
133 \fIaliases\fP, `\|\fBcvs checkout\fP\|' creates all intermediate
134 directories in the working directory, just as if the path had been
135 specified explicitly in the \fBcvs\fP arguments.
136 .SP
137 .nf
138 \fImname\fP [ \fIoptions\fP ] \fIdir\fP [ \fIfiles\fP\|.\|.\|. ] [ \fB&\fP\fImodule\fP\|.\|.\|. ]
139 .fi
140 .SP
141 In the simplest case, this form of module definition reduces to
142 `\|\fImname dir\fP\|'.  This defines all the files in directory
143 \fIdir\fP as module \fImname\fP.  \fIdir\fP is a relative path (from
144 \fB$CVSROOT\fP) to a directory of source in one of the source
145 repositories.  In this case, on \fBcheckout\fP, a single directory
146 called \fImname\fP is created as a working directory; no intermediate
147 directory levels are used by default, even if \fIdir\fP was a path
148 involving several directory levels.
149 .SP
150 By explicitly specifying \fIfiles\fP in the module definition after
151 \fIdir\fP, you can select particular files from directory
152 \fIdir\fP.  The sample definition for \fBmodules\fP is an example of
153 a module defined with a single file from a particular directory.  Here
154 is another example:
155 .SP
156 .nf
157 .ft B
158 m4test  unsupported/gnu/m4 foreach.m4 forloop.m4
159 .ft P
160 .fi
161 .SP
162 With this definition, executing `\|\fBcvs checkout m4test\fP\|'
163 will create a single working directory `\|m4test\|' containing the two
164 files listed, which both come from a common directory several levels
165 deep in the \fBcvs\fP source repository.
166 .SP
167 A module definition can refer to other modules by including
168 `\|\fB&\fP\fImodule\fP\|' in its definition.  \fBcheckout\fP creates
169 a subdirectory for each such \fImodule\fP, in your working directory.
170 .br
171 .I
172 New in \fBcvs\fP 1.3;
173 avoid this feature if sharing module definitions with older versions
174 of \fBcvs\fP.
175 .SP
176 Finally, you can use one or more of the following \fIoptions\fP in
177 module definitions:
178 .SP
179 \&`\|\fB\-d\fP \fIname\fP\|', to name the working directory something
180 other than the module name.
181 .br
182 .I
183 New in \fBcvs\fP 1.3;
184 avoid this feature if sharing module definitions with older versions
185 of \fBcvs\fP.
186 .SP
187 \&`\|\fB\-i\fP \fIprog\fP\|' allows you to specify a program \fIprog\fP
188 to run whenever files in a module are committed.  \fIprog\fP runs with a
189 single argument, the full pathname of the affected directory in a
190 source repository.   The `\|commitinfo\|', `\|loginfo\|', and
191 `\|editinfo\|' files provide other ways to call a program on \fBcommit\fP.
192 .SP
193 `\|\fB\-o\fP \fIprog\fP\|' allows you to specify a program \fIprog\fP
194 to run whenever files in a module are checked out.  \fIprog\fP runs
195 with a single argument, the module name.
196 .SP
197 `\|\fB\-e\fP \fIprog\fP\|' allows you to specify a program \fIprog\fP
198 to run whenever files in a module are exported.  \fIprog\fP runs
199 with a single argument, the module name.
200 .SP
201 `\|\fB\-t\fP \fIprog\fP\|' allows you to specify a program \fIprog\fP
202 to run whenever files in a module are tagged.  \fIprog\fP runs with two
203 arguments:  the module name and the symbolic tag specified to \fBrtag\fP.
204 .SP
205 `\|\fB\-u\fP \fIprog\fP\|' allows you to specify a program \fIprog\fP
206 to run whenever `\|\fBcvs update\fP\|' is executed from the top-level
207 directory of the checked-out module.  \fIprog\fP runs with a
208 single argument, the full path to the source repository for this module.
209 .TP
210 \&\fBcommitinfo\fP, \fBloginfo\fP, \fBrcsinfo\fP, \fBeditinfo\fP
211 These files all specify programs to call at different points in the
212 `\|\fBcvs commit\fP\|' process.  They have a common structure.
213 Each line is a pair of fields: a regular expression, separated by
214 whitespace from a filename or command-line template.
215 Whenever one of the regular expression matches a directory name in the
216 repository, the rest of the line is used.
217 If the line begins with a \fB#\fP character, the entire line is considered
218 a comment and is ignored.
219 Whitespace between the fields is also ignored.
220 .SP
221 For `\|loginfo\|', the rest of the
222 line is a command-line template to execute.
223 The templates can include not only
224 a program name, but whatever list of arguments you wish.  If you write
225 `\|\fB%s\fP\|' somewhere on the argument list, \fBcvs\fP supplies, at
226 that point, the list of files affected by the \fBcommit\fP. 
227 The first entry in the list is the relative path within the source
228 repository where the change is being made.
229 The remaining arguments list the files that are being modified, added, or
230 removed by this \fBcommit\fP invocation.
231 .SP
232 For `\|taginfo\|', the rest of the
233 line is a command-line template to execute.
234 The arguments passed to the command are, in order, the
235 .I tagname ,
236 .I operation
237 (i.e. 
238 .B add
239 for `tag',
240 .B mov
241 for `tag \-F', and
242 .B del
243 for `tag \-d`),
244 .I repository ,
245 and any remaining are pairs of
246 .B "filename revision" .
247 A non-zero exit of the filter program will cause the tag to be aborted.
248 .SP
249 For `\|commitinfo\|', the rest of the line is a command-line template to
250 execute.
251 The template can include not only a program name, but whatever
252 list of arguments you wish.
253 The full path to the current source repository is appended to the template,
254 followed by the file names of any files involved in the commit (added,
255 removed, and modified files).
256 .SP
257 For `\|rcsinfo\|', the rest of the line is the full path to a file that
258 should be loaded into the log message template.
259 .SP
260 For `\|editinfo\|', the rest of the line is a command-line template to
261 execute.
262 The template can include not only a program name, but whatever
263 list of arguments you wish.
264 The full path to the current log message template file is appended to the
265 template.
266 .SP
267 You can use one of two special strings instead of a regular
268 expression: `\|\fBALL\fP\|' specifies a command line template that
269 must always be executed, and `\|\fBDEFAULT\fP\|' specifies a command
270 line template to use if no regular expression is a match.
271 .SP
272 The `\|commitinfo\|' file contains commands to execute \fIbefore\fP any
273 other \fBcommit\fP activity, to allow you to check any conditions that
274 must be satisfied before \fBcommit\fP can proceed.  The rest of the
275 \fBcommit\fP will execute only if all selected commands from this file
276 exit with exit status \fB0\fP.
277 .SP
278 The `\|rcsinfo\|' file allows you to specify \fIlog templates\fP for
279 the \fBcommit\fP logging session; you can use this to provide a form
280 to edit when filling out the \fBcommit\fP log.  The field after the
281 regular expression, in this file, contains filenames (of files
282 containing the logging forms) rather than command templates.
283 .SP
284 The `\|editinfo\|' file allows you to execute a script \fIbefore the
285 commit starts\fP, but after the log information is recorded.  These
286 "edit" scripts can verify information recorded in the log file.  If
287 the edit script exits with a non-zero exit status, the commit is aborted.
288 .SP
289 The `\|loginfo\|' file contains commands to execute \fIat the end\fP
290 of a commit.  The text specified as a commit log message is piped
291 through the command; typical uses include sending mail, filing an
292 article in a newsgroup, or appending to a central file.
293 .TP
294 \&\fBcvsignore\fP, \fB.cvsignore\fP
295 The default list of files (or
296 .BR sh ( 1 )
297 file name patterns) to ignore during `\|\fBcvs update\fP\|'.
298 At startup time, \fBcvs\fP loads the compiled in default list of file name
299 patterns (see
300 .BR cvs ( 1 )).
301 Then the per-repository list included in \fB$CVSROOT/CVSROOT/cvsignore\fP
302 is loaded, if it exists.
303 Then the per-user list is loaded from `\|$HOME/.cvsignore\|'.
304 Finally, as \fBcvs\fP traverses through your directories, it will load any
305 per-directory `\|.cvsignore\|' files whenever it finds one.
306 These per-directory files are only valid for exactly the directory that
307 contains them, not for any sub-directories.
308 .TP
309 .B history
310 Create this file in \fB$CVSROOT/CVSROOT\fP to enable history logging
311 (see the description of `\|\fBcvs history\fP\|').
312 .SH "SEE ALSO"
313 .BR cvs ( 1 ),
314 .SH COPYING
315 Copyright \(co 1992 Cygnus Support, Brian Berliner, and Jeff Polk
316 .PP
317 Permission is granted to make and distribute verbatim copies of
318 this manual provided the copyright notice and this permission notice
319 are preserved on all copies.
320 .PP
321 Permission is granted to copy and distribute modified versions of this
322 manual under the conditions for verbatim copying, provided that the
323 entire resulting derived work is distributed under the terms of a
324 permission notice identical to this one.
325 .PP
326 Permission is granted to copy and distribute translations of this
327 manual into another language, under the above conditions for modified
328 versions, except that this permission notice may be included in
329 translations approved by the Free Software Foundation instead of in
330 the original English.