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