Import (slightly modified) ru.koi8-r.win.kbd:1.1 from FreeBSD (fjoe):
[dragonfly.git] / contrib / cvs-1.12.11 / doc / cvs.1
1 .\" This is the man page for CVS.  It is auto-generated from the
2 .\" cvs.man.header, cvs.texinfo, & cvs.man.footer files.  Please make changes
3 .\" there.  A full copyright & license notice may also be found in cvs.texinfo.
4 .\"
5 .\" Copyright 2004 The Free Software Foundation,
6 .\"                Derek R. Price,
7 .\"                & Ximbiot <http://ximbiot.com>
8 .\"
9 .\" This documentation is free software; you can redistribute it and/or modify
10 .\" it under the terms of the GNU General Public License as published by
11 .\" the Free Software Foundation; either version 2, or (at your option)
12 .\" any later version.
13 .\"
14 .\" This documentation is distributed in the hope that it will be useful,
15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17 .\" GNU General Public License for more details.
18 .\"
19 .\" You should have received a copy of the GNU General Public License
20 .\" along with this documentation; if not, write to the Free Software
21 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
22 .de Id
23 .ds Rv \\$3
24 .ds Dt \\$4
25 ..
26 .TH CVS 1 "\*(Dt"
27 .\" Full space in nroff; half space in troff
28 .de SP
29 .if n .sp
30 .if t .sp .5
31 ..
32 .\" quoted command
33 .de `
34 .RB ` "\|\\$1\|" '\\$2
35 ..
36 .SH "NAME"
37 cvs \- Concurrent Versions System
38 .SH "SYNOPSIS"
39 .TP
40 \fBcvs\fP [ \fIcvs_options\fP ]
41 .I cvs_command
42 [
43 .I command_options
44 ] [
45 .I command_args
46 ]
47 .SH "NOTE"
48 .IX "revision control system" "\fLcvs\fR"
49 .IX  cvs  ""  "\fLcvs\fP \- concurrent versions system"
50 .IX  "concurrent versions system \- \fLcvs\fP"
51 .IX  "release control system"  "cvs command"  ""  "\fLcvs\fP \- concurrent versions system"
52 .IX  "source control system"  "cvs command"  ""  "\fLcvs\fP \- concurrent versions system"
53 .IX  revisions  "cvs command"  ""  "\fLcvs\fP \- source control"
54 This manpage is a summary of some of the features of
55 \fBcvs\fP.  It is auto-generated from an appendix of the CVS manual.
56 For more in-depth documentation, please consult the
57 Cederqvist manual (via the
58 .B info CVS
59 command or otherwise,
60 as described in the SEE ALSO section of this manpage).  Cross-references
61 in this man page refer to nodes in the same.
62 .SH "CVS commands"
63 .SS "Guide to CVS commands"
64 .SP
65 This appendix describes the overall structure of
66 \fBcvs\fR commands, and describes some commands in
67 detail (others are described elsewhere; for a quick
68 reference to \fBcvs\fR commands, see node `Invoking CVS\(aq in the CVS manual).
69 .SP
70 .SH "Structure"
71 .SS "Overall structure of CVS commands"
72 .IX "Structure"
73 .IX "CVS command structure"
74 .IX "Command structure"
75 .IX "Format of CVS commands"
76 .SP
77 The overall format of all \fBcvs\fR commands is:
78 .SP
79 .PD 0
80 .SP
81 .IP "" 2
82 cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
83
84 .PD
85 .IP "" 0
86 .SP
87 .IP "" 0
88 \fBcvs\fR
89 .IP "" 2
90 The name of the \fBcvs\fR program.
91 .SP
92 .IP "" 0
93 \fBcvs_options\fR
94 .IP "" 2
95 Some options that affect all sub-commands of \fBcvs\fR.  These are
96 described below.
97 .SP
98 .IP "" 0
99 \fBcvs_command\fR
100 .IP "" 2
101 One of several different sub-commands.  Some of the commands have
102 aliases that can be used instead; those aliases are noted in the
103 reference manual for that command.  There are only two situations
104 where you may omit \fBcvs_command\fR: \fBcvs -H\fR elicits a
105 list of available commands, and \fBcvs -v\fR displays version
106 information on \fBcvs\fR itself.
107 .SP
108 .IP "" 0
109 \fBcommand_options\fR
110 .IP "" 2
111 Options that are specific for the command.
112 .SP
113 .IP "" 0
114 \fBcommand_args\fR
115 .IP "" 2
116 Arguments to the commands.
117 .SP
118 There is unfortunately some confusion between
119 \fBcvs_options\fR and \fBcommand_options\fR.
120 When given as a \fBcvs_option\fR, some options only
121 affect some of the commands.  When given as a
122 \fBcommand_option\fR it may have a different meaning, and
123 be accepted by more commands.  In other words, do not
124 take the above categorization too seriously.  Look at
125 the documentation instead.
126 .SP
127 .SH "Exit status"
128 .SS "CVS\(aqs exit status"
129 .IX "Exit status, of CVS"
130 .SP
131 \fBcvs\fR can indicate to the calling environment whether it
132 succeeded or failed by setting its \fIexit status\fR.
133 The exact way of testing the exit status will vary from
134 one operating system to another.  For example in a unix
135 shell script the \fB$?\fR variable will be 0 if the
136 last command returned a successful exit status, or
137 greater than 0 if the exit status indicated failure.
138 .SP
139 If \fBcvs\fR is successful, it returns a successful status;
140 if there is an error, it prints an error message and
141 returns a failure status.  The one exception to this is
142 the \fBcvs diff\fR command.  It will return a
143 successful status if it found no differences, or a
144 failure status if there were differences or if there
145 was an error.  Because this behavior provides no good
146 way to detect errors, in the future it is possible that
147 \fBcvs diff\fR will be changed to behave like the
148 other \fBcvs\fR commands.
149 .SP
150 .SH "~/.cvsrc"
151 .SS "Default options and the ~/.cvsrc file"
152 .IX "\&.cvsrc file"
153 .IX "Option defaults"
154 .SP
155 There are some \fBcommand_options\fR that are used so
156 often that you might have set up an alias or some other
157 means to make sure you always specify that option.  One
158 example (the one that drove the implementation of the
159 \fB.cvsrc\fR support, actually) is that many people find the
160 default output of the \fBdiff\fR command to be very
161 hard to read, and that either context diffs or unidiffs
162 are much easier to understand.
163 .SP
164 The \fB~/.cvsrc\fR file is a way that you can add
165 default options to \fBcvs_commands\fR within cvs,
166 instead of relying on aliases or other shell scripts.
167 .SP
168 The format of the \fB~/.cvsrc\fR file is simple.  The
169 file is searched for a line that begins with the same
170 name as the \fBcvs_command\fR being executed.  If a
171 match is found, then the remainder of the line is split
172 up (at whitespace characters) into separate options and
173 added to the command arguments \fIbefore\fR any
174 options from the command line.
175 .SP
176 If a command has two names (e.g., \fBcheckout\fR and
177 \fBco\fR), the official name, not necessarily the one
178 used on the command line, will be used to match against
179 the file.  So if this is the contents of the user\(aqs
180 \fB~/.cvsrc\fR file:
181 .SP
182 .PD 0
183 .SP
184 .IP "" 2
185 log -N
186 .IP "" 2
187 diff -uN
188 .IP "" 2
189 rdiff -u
190 .IP "" 2
191 update -Pd
192 .IP "" 2
193 checkout -P
194 .IP "" 2
195 release -d
196
197 .PD
198 .IP "" 0
199 .SP
200 the command \fBcvs checkout foo\fR would have the
201 \fB-P\fR option added to the arguments, as well as
202 \fBcvs co foo\fR.
203 .SP
204 With the example file above, the output from \fBcvs
205 diff foobar\fR will be in unidiff format.  \fBcvs diff
206 -c foobar\fR will provide context diffs, as usual.
207 Getting "old" format diffs would be slightly more
208 complicated, because \fBdiff\fR doesn\(aqt have an option
209 to specify use of the "old" format, so you would need
210 \fBcvs -f diff foobar\fR.
211 .SP
212 In place of the command name you can use \fBcvs\fR to
213 specify global options (see node `Global options\(aq in the CVS manual).  For
214 example the following line in \fB.cvsrc\fR
215 .SP
216 .PD 0
217 .SP
218 .IP "" 2
219 cvs -z6
220
221 .PD
222 .IP "" 0
223 .SP
224 causes \fBcvs\fR to use compression level 6.
225 .SP
226 .SH "Global options"
227 .IX "Options, global"
228 .IX "Global options"
229 .IX "Left-hand options"
230 .SP
231 The available \fBcvs_options\fR (that are given to the
232 left of \fBcvs_command\fR) are:
233 .SP
234 .IP "" 0
235 \fB--allow-root=\fIrootdir\fB\fR
236 .IP "" 2
237 May be invoked multiple times to specify one legal \fBcvsroot\fR directory with
238 each invocation.  Also causes CVS to preparse the configuration file for each
239 specified root, which can be useful when configuring write proxies,  See
240 see node `Password authentication server\(aq in the CVS manual & see node `Write proxies\(aq in the CVS manual.
241 .SP
242 .IX "Authentication, stream"
243 .IX "Stream authentication"
244 .IP "" 0
245 \fB-a\fR
246 .IP "" 2
247 Authenticate all communication between the client and
248 the server.  Only has an effect on the \fBcvs\fR client.
249 As of this writing, this is only implemented when using
250 a GSSAPI connection (see node `GSSAPI authenticated\(aq in the CVS manual).
251 Authentication prevents certain sorts of attacks
252 involving hijacking the active \fBtcp\fR connection.
253 Enabling authentication does not enable encryption.
254 .SP
255 .IX "RCSBIN, overriding"
256 .IX "Overriding RCSBIN"
257 .IP "" 0
258 \fB-b \fIbindir\fB\fR
259 .IP "" 2
260 In \fBcvs\fR 1.9.18 and older, this specified that
261 \fBrcs\fR programs are in the \fIbindir\fR directory.
262 Current versions of \fBcvs\fR do not run \fBrcs\fR
263 programs; for compatibility this option is accepted,
264 but it does nothing.
265 .SP
266 .IX "TMPDIR, overriding"
267 .IX "Overriding TMPDIR"
268 .IP "" 0
269 \fB-T \fItempdir\fB\fR
270 .IP "" 2
271 Use \fItempdir\fR as the directory where temporary files are
272 located.  Overrides the setting of the \fB$TMPDIR\fR environment
273 variable and any precompiled directory.  This parameter should be
274 specified as an absolute pathname.
275 (When running client/server, \fB-T\fR affects only the local process;
276 specifying \fB-T\fR for the client has no effect on the server and
277 vice versa.)
278 .SP
279 .IX "CVSROOT, overriding"
280 .IX "Overriding CVSROOT"
281 .IP "" 0
282 \fB-d \fIcvs_root_directory\fB\fR
283 .IP "" 2
284 Use \fIcvs_root_directory\fR as the root directory
285 pathname of the repository.  Overrides the setting of
286 the \fB$CVSROOT\fR environment variable.  see node `Repository\(aq in the CVS manual.
287 .SP
288 .IX "EDITOR, overriding"
289 .IX "Overriding EDITOR"
290 .IP "" 0
291 \fB-e \fIeditor\fB\fR
292 .IP "" 2
293 Use \fIeditor\fR to enter revision log information.  Overrides the
294 setting of the \fB$CVSEDITOR\fR and \fB$EDITOR\fR
295 environment variables.  For more information, see
296 see node `Committing your changes\(aq in the CVS manual.
297 .SP
298 .IP "" 0
299 \fB-f\fR
300 .IP "" 2
301 Do not read the \fB~/.cvsrc\fR file.  This
302 option is most often used because of the
303 non-orthogonality of the \fBcvs\fR option set.  For
304 example, the \fBcvs log\fR option \fB-N\fR (turn off
305 display of tag names) does not have a corresponding
306 option to turn the display on.  So if you have
307 \fB-N\fR in the \fB~/.cvsrc\fR entry for \fBlog\fR,
308 you may need to use \fB-f\fR to show the tag names.
309 .SP
310 .IP "" 0
311 \fB-H\fR
312 .IP "" 2
313 .IP "" 0
314 \fB--help\fR
315 .IP "" 2
316 Display usage information about the specified \fBcvs_command\fR
317 (but do not actually execute the command).  If you don\(aqt specify
318 a command name, \fBcvs -H\fR displays overall help for
319 \fBcvs\fR, including a list of other help options.
320 .SP
321 .IX "Read-only repository mode"
322 .IP "" 0
323 \fB-R\fR
324 .IP "" 2
325 Turns on read-only repository mode.  This allows one to check out from a
326 read-only repository, such as within an anoncvs server, or from a \fBcd-rom\fR
327 repository.
328 .SP
329 Same effect as if the \fBCVSREADONLYFS\fR environment
330 variable is set. Using \fB-R\fR can also considerably
331 speed up checkouts over NFS.
332 .SP
333 .IX "Read-only mode"
334 .IP "" 0
335 \fB-n\fR
336 .IP "" 2
337 Do not change any files.  Attempt to execute the
338 \fBcvs_command\fR, but only to issue reports; do not remove,
339 update, or merge any existing files, or create any new files.
340 .SP
341 Note that \fBcvs\fR will not necessarily produce exactly
342 the same output as without \fB-n\fR.  In some cases
343 the output will be the same, but in other cases
344 \fBcvs\fR will skip some of the processing that would
345 have been required to produce the exact same output.
346 .SP
347 .IP "" 0
348 \fB-Q\fR
349 .IP "" 2
350 Cause the command to be really quiet; the command will only
351 generate output for serious problems.
352 .SP
353 .IP "" 0
354 \fB-q\fR
355 .IP "" 2
356 Cause the command to be somewhat quiet; informational messages,
357 such as reports of recursion through subdirectories, are
358 suppressed.
359 .SP
360 .IX "Read-only files, and -r"
361 .IP "" 0
362 \fB-r\fR
363 .IP "" 2
364 Make new working files read-only.  Same effect
365 as if the \fB$CVSREAD\fR environment variable is set
366 (see node `Environment variables\(aq in the CVS manual).  The default is to
367 make working files writable, unless watches are on
368 (see node `Watches\(aq in the CVS manual).
369 .SP
370 .IP "" 0
371 \fB-s \fIvariable\fB=\fIvalue\fB\fR
372 .IP "" 2
373 Set a user variable (see node `Variables\(aq in the CVS manual).
374 .SP
375 .IX "Trace"
376 .IP "" 0
377 \fB-t\fR
378 .IP "" 2
379 Trace program execution; display messages showing the steps of
380 \fBcvs\fR activity.  Particularly useful with \fB-n\fR to explore the
381 potential impact of an unfamiliar command.
382 .SP
383 .IP "" 0
384 \fB-v\fR
385 .IP "" 2
386 .IP "" 0
387 \fB--version\fR
388 .IP "" 2
389 Display version and copyright information for \fBcvs\fR.
390 .SP
391 .IX "CVSREAD, overriding"
392 .IX "Overriding CVSREAD"
393 .IP "" 0
394 \fB-w\fR
395 .IP "" 2
396 Make new working files read-write.  Overrides the
397 setting of the \fB$CVSREAD\fR environment variable.
398 Files are created read-write by default, unless \fB$CVSREAD\fR is
399 set or \fB-r\fR is given.
400 .SP
401 .IP "" 0
402 \fB-x\fR
403 .IP "" 2
404 .IX "Encryption"
405 Encrypt all communication between the client and the
406 server.  Only has an effect on the \fBcvs\fR client.  As
407 of this writing, this is only implemented when using a
408 GSSAPI connection (see node `GSSAPI authenticated\(aq in the CVS manual) or a
409 Kerberos connection (see node `Kerberos authenticated\(aq in the CVS manual).
410 Enabling encryption implies that message traffic is
411 also authenticated.  Encryption support is not
412 available by default; it must be enabled using a
413 special configure option, \fB--enable-encryption\fR,
414 when you build \fBcvs\fR.
415 .SP
416 .IP "" 0
417 \fB-z \fIgzip-level\fB\fR
418 .IP "" 2
419 .IX "Compression"
420 .IX "Gzip"
421 Set the compression level.
422 Valid levels are 1 (high speed, low compression) to
423 9 (low speed, high compression), or 0 to disable
424 compression (the default).
425 Only has an effect on the \fBcvs\fR client.
426 .SP
427 .SP
428 .SH "Common options"
429 .SS "Common command options"
430 .IX "Common options"
431 .IX "Right-hand options"
432 .SP
433 This section describes the \fBcommand_options\fR that
434 are available across several \fBcvs\fR commands.  These
435 options are always given to the right of
436 \fBcvs_command\fR. Not all
437 commands support all of these options; each option is
438 only supported for commands where it makes sense.
439 However, when a command has one of these options you
440 can almost always count on the same behavior of the
441 option as in other commands.  (Other command options,
442 which are listed with the individual commands, may have
443 different behavior from one \fBcvs\fR command to the other).
444 .SP
445 \fBNote: the \fBhistory\fB command is an exception; it supports
446 many options that conflict even with these standard options.\fR
447 .SP
448 .IX "Dates"
449 .IX "Time"
450 .IX "Specifying dates"
451 .IP "" 0
452 \fB-D \fIdate_spec\fB\fR
453 .IP "" 2
454 Use the most recent revision no later than \fIdate_spec\fR.
455 \fIdate_spec\fR is a single argument, a date description
456 specifying a date in the past.
457 .SP
458 The specification is \fIsticky\fR when you use it to make a
459 private copy of a source file; that is, when you get a working
460 file using \fB-D\fR, \fBcvs\fR records the date you specified, so that
461 further updates in the same directory will use the same date
462 (for more information on sticky tags/dates, see node `Sticky tags\(aq in the CVS manual).
463 .SP
464 \fB-D\fR is available with the \fBannotate\fR, \fBcheckout\fR,
465 \fBdiff\fR, \fBexport\fR, \fBhistory\fR, \fBls\fR,
466 \fBrdiff\fR, \fBrls\fR, \fBrtag\fR, \fBtag\fR, and \fBupdate\fR commands.
467 (The \fBhistory\fR command uses this option in a
468 slightly different way; see node `history options\(aq in the CVS manual).
469 .SP
470 For a complete description of the date formats accepted by \fBcvs\fR,
471 see node `Date input formats\(aq in the CVS manual.
472 .SP
473 Remember to quote the argument to the \fB-D\fR
474 flag so that your shell doesn\(aqt interpret spaces as
475 argument separators.  A command using the \fB-D\fR
476 flag can look like this:
477 .SP
478 .PD 0
479 .SP
480 .IP "" 4
481 $ cvs diff -D "1 hour ago" cvs.texinfo
482
483 .PD
484 .IP "" 2
485 .SP
486 .IX "Forcing a tag match"
487 .IP "" 0
488 \fB-f\fR
489 .IP "" 2
490 When you specify a particular date or tag to \fBcvs\fR commands, they
491 normally ignore files that do not contain the tag (or did not
492 exist prior to the date) that you specified.  Use the \fB-f\fR option
493 if you want files retrieved even when there is no match for the
494 tag or date.  (The most recent revision of the file
495 will be used).
496 .SP
497 Note that even with \fB-f\fR, a tag that you specify
498 must exist (that is, in some file, not necessary in
499 every file).  This is so that \fBcvs\fR will continue to
500 give an error if you mistype a tag name.
501 .SP
502 \fB-f\fR is available with these commands:
503 \fBannotate\fR, \fBcheckout\fR, \fBexport\fR,
504 \fBrdiff\fR, \fBrtag\fR, and \fBupdate\fR.
505 .SP
506 \fBWARNING:  The \fBcommit\fB and \fBremove\fB
507 commands also have a
508 \fB-f\fB option, but it has a different behavior for
509 those commands.  See see node `commit options\(aq in the CVS manual, and
510 see node `Removing files\(aq in the CVS manual.\fR
511 .SP
512 .IP "" 0
513 \fB-k \fIkflag\fB\fR
514 .IP "" 2
515 Override the default processing of RCS keywords other than
516 \fB-kb\fR.  see node `Keyword substitution\(aq in the CVS manual, for the meaning of
517 \fIkflag\fR.  Used with the \fBcheckout\fR and \fBupdate\fR
518 commands, your \fIkflag\fR specification is
519 \fIsticky\fR; that is, when you use this option
520 with a \fBcheckout\fR or \fBupdate\fR command,
521 \fBcvs\fR associates your selected \fIkflag\fR with any files
522 it operates on, and continues to use that \fIkflag\fR with future
523 commands on the same files until you specify otherwise.
524 .SP
525 The \fB-k\fR option is available with the \fBadd\fR,
526 \fBcheckout\fR, \fBdiff\fR, \fBexport\fR, \fBimport\fR and
527 \fBupdate\fR commands.
528 .SP
529 \fBWARNING: Prior to CVS version 1.12.2, the \fB-k\fB flag
530 overrode the \fB-kb\fB indication for a binary file.  This could
531 sometimes corrupt binary files.  see node `Merging and keywords\(aq in the CVS manual, for
532 more.\fR
533 .SP
534 .IP "" 0
535 \fB-l\fR
536 .IP "" 2
537 Local; run only in current working directory, rather than
538 recursing through subdirectories.
539 .SP
540 Available with the following commands: \fBannotate\fR, \fBcheckout\fR,
541 \fBcommit\fR, \fBdiff\fR, \fBedit\fR, \fBeditors\fR, \fBexport\fR,
542 \fBlog\fR, \fBrdiff\fR, \fBremove\fR, \fBrtag\fR,
543 \fBstatus\fR, \fBtag\fR, \fBunedit\fR, \fBupdate\fR, \fBwatch\fR,
544 and \fBwatchers\fR.
545 .SP
546 .IX "Editor, avoiding invocation of"
547 .IX "Avoiding editor invocation"
548 .IP "" 0
549 \fB-m \fImessage\fB\fR
550 .IP "" 2
551 Use \fImessage\fR as log information, instead of
552 invoking an editor.
553 .SP
554 Available with the following commands: \fBadd\fR,
555 \fBcommit\fR and \fBimport\fR.
556 .SP
557 .IP "" 0
558 \fB-n\fR
559 .IP "" 2
560 Do not run any tag program.  (A program can be
561 specified to run in the modules
562 database (see node `modules\(aq in the CVS manual); this option bypasses it).
563 .SP
564 \fBNote: this is not the same as the \fBcvs -n\fB
565 program option, which you can specify to the left of a cvs command!\fR
566 .SP
567 Available with the \fBcheckout\fR, \fBcommit\fR, \fBexport\fR,
568 and \fBrtag\fR commands.
569 .SP
570 .IP "" 0
571 \fB-P\fR
572 .IP "" 2
573 Prune empty directories.  See see node `Removing directories\(aq in the CVS manual.
574 .SP
575 .IP "" 0
576 \fB-p\fR
577 .IP "" 2
578 Pipe the files retrieved from the repository to standard output,
579 rather than writing them in the current directory.  Available
580 with the \fBcheckout\fR and \fBupdate\fR commands.
581 .SP
582 .IP "" 0
583 \fB-R\fR
584 .IP "" 2
585 Process directories recursively.  This is the default for all \fBcvs\fR
586 commands, with the exception of \fBls\fR & \fBrls\fR.
587 .SP
588 Available with the following commands: \fBannotate\fR, \fBcheckout\fR,
589 \fBcommit\fR, \fBdiff\fR, \fBedit\fR, \fBeditors\fR, \fBexport\fR,
590 \fBls\fR, \fBrdiff\fR, \fBremove\fR, \fBrls\fR, \fBrtag\fR,
591 \fBstatus\fR, \fBtag\fR, \fBunedit\fR, \fBupdate\fR, \fBwatch\fR,
592 and \fBwatchers\fR.
593 .SP
594 .IP "" 0
595 \fB-r \fItag\fB\fR
596 .IP "" 2
597 .IX "HEAD, special tag"
598 .IX "BASE, special tag"
599 Use the revision specified by the \fItag\fR argument instead of the
600 default \fIhead\fR revision.  As well as arbitrary tags defined
601 with the \fBtag\fR or \fBrtag\fR command, two special tags are
602 always available: \fBHEAD\fR refers to the most recent version
603 available in the repository, and \fBBASE\fR refers to the
604 revision you last checked out into the current working directory.
605 .SP
606 The tag specification is sticky when you use this
607 with \fBcheckout\fR or \fBupdate\fR to make your own
608 copy of a file: \fBcvs\fR remembers the tag and continues to use it on
609 future update commands, until you specify otherwise (for more information
610 on sticky tags/dates, see node `Sticky tags\(aq in the CVS manual).
611 .SP
612 The tag can be either a symbolic or numeric tag, as
613 described in see node `Tags\(aq in the CVS manual, or the name of a branch, as
614 described in see node `Branching and merging\(aq in the CVS manual.
615 .SP
616 Specifying the \fB-q\fR global option along with the
617 \fB-r\fR command option is often useful, to suppress
618 the warning messages when the \fBrcs\fR file
619 does not contain the specified tag.
620 .SP
621 \fBNote: this is not the same as the overall \fBcvs -r\fB option,
622 which you can specify to the left of a \fBcvs\fB command!\fR
623 .SP
624 \fB-r\fR is available with the \fBannotate\fR, \fBcheckout\fR,
625 \fBcommit\fR, \fBdiff\fR, \fBhistory\fR, \fBexport\fR, \fBrdiff\fR, 
626 \fBrtag\fR, and \fBupdate\fR commands.
627 .SP
628 .IP "" 0
629 \fB-W\fR
630 .IP "" 2
631 Specify file names that should be filtered.  You can
632 use this option repeatedly.  The spec can be a file
633 name pattern of the same type that you can specify in
634 the \fB.cvswrappers\fR file.
635 Available with the following commands: \fBimport\fR,
636 and \fBupdate\fR.
637 .SP
638 .SP
639 .SH "admin"
640 .SS "Administration"
641 .IX "Admin (subcommand)"
642 .SP
643 .IP "\(bu" 2
644 Requires: repository, working directory.
645 .IP "\(bu" 2
646 Changes: repository.
647 .IP "\(bu" 2
648 Synonym: rcs
649 .SP
650 This is the \fBcvs\fR interface to assorted
651 administrative facilities.  Some of them have
652 questionable usefulness for \fBcvs\fR but exist for
653 historical purposes.  Some of the questionable options
654 are likely to disappear in the future.  This command
655 \fIdoes\fR work recursively, so extreme care should be
656 used.
657 .SP
658 .IX "cvsadmin"
659 .IX "UserAdminOptions, in CVSROOT/config"
660 On unix, if there is a group named \fBcvsadmin\fR,
661 only members of that group can run \fBcvs admin\fR
662 commands, except for those specified using the
663 \fBUserAdminOptions\fR configuration option in the
664 \fBCVSROOT/config\fR file.  Options specified using
665 \fBUserAdminOptions\fR can be run by any user.  See
666 see node `config\(aq in the CVS manual for more on \fBUserAdminOptions\fR.
667 .SP
668 The \fBcvsadmin\fR group should exist on the server,
669 or any system running the non-client/server \fBcvs\fR.
670 To disallow \fBcvs admin\fR for all users, create a
671 group with no users in it.  On NT, the \fBcvsadmin\fR
672 feature does not exist and all users
673 can run \fBcvs admin\fR.
674 .SP
675 .SH "admin options"
676 .SP
677 Some of these options have questionable usefulness for
678 \fBcvs\fR but exist for historical purposes.  Some even
679 make it impossible to use \fBcvs\fR until you undo the
680 effect!
681 .SP
682 .IP "" 0
683 \fB-A\fIoldfile\fB\fR
684 .IP "" 2
685 Might not work together with \fBcvs\fR.  Append the
686 access list of \fIoldfile\fR to the access list of the
687 \fBrcs\fR file.
688 .SP
689 .IP "" 0
690 \fB-a\fIlogins\fB\fR
691 .IP "" 2
692 Might not work together with \fBcvs\fR.  Append the
693 login names appearing in the comma-separated list
694 \fIlogins\fR to the access list of the \fBrcs\fR file.
695 .SP
696 .IP "" 0
697 \fB-b[\fIrev\fB]\fR
698 .IP "" 2
699 Set the default branch to \fIrev\fR.  In \fBcvs\fR, you
700 normally do not manipulate default branches; sticky
701 tags (see node `Sticky tags\(aq in the CVS manual) are a better way to decide
702 which branch you want to work on.  There is one reason
703 to run \fBcvs admin -b\fR: to revert to the vendor\(aqs
704 version when using vendor branches (see node `Reverting
705 local changes\(aq in the CVS manual).
706 There can be no space between \fB-b\fR and its argument.
707 .SP
708 .IX "Comment leader"
709 .IP "" 0
710 \fB-c\fIstring\fB\fR
711 .IP "" 2
712 Sets the comment leader to \fIstring\fR.  The comment
713 leader is not used by current versions of \fBcvs\fR or
714 \fBrcs\fR 5.7.  Therefore, you can almost surely not
715 worry about it.  see node `Keyword substitution\(aq in the CVS manual.
716 .SP
717 .IP "" 0
718 \fB-e[\fIlogins\fB]\fR
719 .IP "" 2
720 Might not work together with \fBcvs\fR.  Erase the login
721 names appearing in the comma-separated list
722 \fIlogins\fR from the access list of the RCS file.  If
723 \fIlogins\fR is omitted, erase the entire access list.
724 There can be no space between \fB-e\fR and its argument.
725 .SP
726 .IP "" 0
727 \fB-I\fR
728 .IP "" 2
729 Run interactively, even if the standard input is not a
730 terminal.  This option does not work with the
731 client/server \fBcvs\fR and is likely to disappear in
732 a future release of \fBcvs\fR.
733 .SP
734 .IP "" 0
735 \fB-i\fR
736 .IP "" 2
737 Useless with \fBcvs\fR.  This creates and initializes a
738 new \fBrcs\fR file, without depositing a revision.  With
739 \fBcvs\fR, add files with the \fBcvs add\fR command
740 (see node `Adding files\(aq in the CVS manual).
741 .SP
742 .IP "" 0
743 \fB-k\fIsubst\fB\fR
744 .IP "" 2
745 Set the default keyword
746 substitution to \fIsubst\fR.  see node `Keyword
747 substitution\(aq in the CVS manual.  Giving an explicit \fB-k\fR option to
748 \fBcvs update\fR, \fBcvs export\fR, or \fBcvs
749 checkout\fR overrides this default.
750 .SP
751 .IP "" 0
752 \fB-l[\fIrev\fB]\fR
753 .IP "" 2
754 Lock the revision with number \fIrev\fR.  If a branch
755 is given, lock the latest revision on that branch.  If
756 \fIrev\fR is omitted, lock the latest revision on the
757 default branch.  There can be no space between
758 \fB-l\fR and its argument.
759 .SP
760 This can be used in conjunction with the
761 \fBrcslock.pl\fR script in the \fBcontrib\fR
762 directory of the \fBcvs\fR source distribution to
763 provide reserved checkouts (where only one user can be
764 editing a given file at a time).  See the comments in
765 that file for details (and see the \fBREADME\fR file
766 in that directory for disclaimers about the unsupported
767 nature of contrib).  According to comments in that
768 file, locking must set to strict (which is the default).
769 .SP
770 .IP "" 0
771 \fB-L\fR
772 .IP "" 2
773 Set locking to strict.  Strict locking means that the
774 owner of an RCS file is not exempt from locking for
775 checkin.  For use with \fBcvs\fR, strict locking must be
776 set; see the discussion under the \fB-l\fR option above.
777 .SP
778 .IX "Changing a log message"
779 .IX "Replacing a log message"
780 .IX "Correcting a log message"
781 .IX "Fixing a log message"
782 .IX "Log message, correcting"
783 .IP "" 0
784 \fB-m\fIrev\fB:\fImsg\fB\fR
785 .IP "" 2
786 Replace the log message of revision \fIrev\fR with
787 \fImsg\fR.
788 .SP
789 .IP "" 0
790 \fB-N\fIname\fB[:[\fIrev\fB]]\fR
791 .IP "" 2
792 Act like \fB-n\fR, except override any previous
793 assignment of \fIname\fR.  For use with magic branches,
794 see see node `Magic branch numbers\(aq in the CVS manual.
795 .SP
796 .IP "" 0
797 \fB-n\fIname\fB[:[\fIrev\fB]]\fR
798 .IP "" 2
799 Associate the symbolic name \fIname\fR with the branch
800 or revision \fIrev\fR.  It is normally better to use
801 \fBcvs tag\fR or \fBcvs rtag\fR instead.  Delete the
802 symbolic name if both \fB:\fR and \fIrev\fR are
803 omitted; otherwise, print an error message if
804 \fIname\fR is already associated with another number.
805 If \fIrev\fR is symbolic, it is expanded before
806 association.  A \fIrev\fR consisting of a branch number
807 followed by a \fB.\fR stands for the current latest
808 revision in the branch.  A \fB:\fR with an empty
809 \fIrev\fR stands for the current latest revision on the
810 default branch, normally the trunk.  For example,
811 \fBcvs admin -n\fIname\fB:\fR associates \fIname\fR with the
812 current latest revision of all the RCS files;
813 this contrasts with \fBcvs admin -n\fIname\fB:$\fR which
814 associates \fIname\fR with the revision numbers
815 extracted from keyword strings in the corresponding
816 working files.
817 .SP
818 .IX "Deleting revisions"
819 .IX "Outdating revisions"
820 .IX "Saving space"
821 .IP "" 0
822 \fB-o\fIrange\fB\fR
823 .IP "" 2
824 Deletes (\fIoutdates\fR) the revisions given by
825 \fIrange\fR.
826 .SP
827 Note that this command can be quite dangerous unless
828 you know \fIexactly\fR what you are doing (for example
829 see the warnings below about how the
830 \fIrev1\fR:\fIrev2\fR syntax is confusing).
831 .SP
832 If you are short on disc this option might help you.
833 But think twice before using it\(emthere is no way short
834 of restoring the latest backup to undo this command!
835 If you delete different revisions than you planned,
836 either due to carelessness or (heaven forbid) a \fBcvs\fR
837 bug, there is no opportunity to correct the error
838 before the revisions are deleted.  It probably would be
839 a good idea to experiment on a copy of the repository
840 first.
841 .SP
842 Specify \fIrange\fR in one of the following ways:
843 .SP
844 .IP "" 2
845 \fB\fIrev1\fB::\fIrev2\fB\fR
846 .IP "" 4
847 Collapse all revisions between rev1 and rev2, so that
848 \fBcvs\fR only stores the differences associated with going
849 from rev1 to rev2, not intermediate steps.  For
850 example, after \fB-o 1.3::1.5\fR one can retrieve
851 revision 1.3, revision 1.5, or the differences to get
852 from 1.3 to 1.5, but not the revision 1.4, or the
853 differences between 1.3 and 1.4.  Other examples:
854 \fB-o 1.3::1.4\fR and \fB-o 1.3::1.3\fR have no
855 effect, because there are no intermediate revisions to
856 remove.
857 .SP
858 .IP "" 2
859 \fB::\fIrev\fB\fR
860 .IP "" 4
861 Collapse revisions between the beginning of the branch
862 containing \fIrev\fR and \fIrev\fR itself.  The
863 branchpoint and \fIrev\fR are left intact.  For
864 example, \fB-o ::1.3.2.6\fR deletes revision 1.3.2.1,
865 revision 1.3.2.5, and everything in between, but leaves
866 1.3 and 1.3.2.6 intact.
867 .SP
868 .IP "" 2
869 \fB\fIrev\fB::\fR
870 .IP "" 4
871 Collapse revisions between \fIrev\fR and the end of the
872 branch containing \fIrev\fR.  Revision \fIrev\fR is
873 left intact but the head revision is deleted.
874 .SP
875 .IP "" 2
876 \fB\fIrev\fB\fR
877 .IP "" 4
878 Delete the revision \fIrev\fR.  For example, \fB-o
879 1.3\fR is equivalent to \fB-o 1.2::1.4\fR.
880 .SP
881 .IP "" 2
882 \fB\fIrev1\fB:\fIrev2\fB\fR
883 .IP "" 4
884 Delete the revisions from \fIrev1\fR to \fIrev2\fR,
885 inclusive, on the same branch.  One will not be able to
886 retrieve \fIrev1\fR or \fIrev2\fR or any of the
887 revisions in between.  For example, the command
888 \fBcvs admin -oR_1_01:R_1_02 \&.\fR is rarely useful.
889 It means to delete revisions up to, and including, the
890 tag R_1_02.  But beware!  If there are files that have not
891 changed between R_1_02 and R_1_03 the file will have
892 \fIthe same\fR numerical revision number assigned to
893 the tags R_1_02 and R_1_03.  So not only will it be
894 impossible to retrieve R_1_02; R_1_03 will also have to
895 be restored from the tapes!  In most cases you want to
896 specify \fIrev1\fR::\fIrev2\fR instead.
897 .SP
898 .IP "" 2
899 \fB:\fIrev\fB\fR
900 .IP "" 4
901 Delete revisions from the beginning of the
902 branch containing \fIrev\fR up to and including
903 \fIrev\fR.
904 .SP
905 .IP "" 2
906 \fB\fIrev\fB:\fR
907 .IP "" 4
908 Delete revisions from revision \fIrev\fR, including
909 \fIrev\fR itself, to the end of the branch containing
910 \fIrev\fR.
911 .SP
912 None of the revisions to be deleted may have
913 branches or locks.
914 .SP
915 If any of the revisions to be deleted have symbolic
916 names, and one specifies one of the \fB::\fR syntaxes,
917 then \fBcvs\fR will give an error and not delete any
918 revisions.  If you really want to delete both the
919 symbolic names and the revisions, first delete the
920 symbolic names with \fBcvs tag -d\fR, then run
921 \fBcvs admin -o\fR.  If one specifies the
922 non-\fB::\fR syntaxes, then \fBcvs\fR will delete the
923 revisions but leave the symbolic names pointing to
924 nonexistent revisions.  This behavior is preserved for
925 compatibility with previous versions of \fBcvs\fR, but
926 because it isn\(aqt very useful, in the future it may
927 change to be like the \fB::\fR case.
928 .SP
929 Due to the way \fBcvs\fR handles branches \fIrev\fR
930 cannot be specified symbolically if it is a branch.
931 see node `Magic branch numbers\(aq in the CVS manual, for an explanation.
932 .SP
933 Make sure that no-one has checked out a copy of the
934 revision you outdate.  Strange things will happen if he
935 starts to edit it and tries to check it back in.  For
936 this reason, this option is not a good way to take back
937 a bogus commit; commit a new revision undoing the bogus
938 change instead (see node `Merging two revisions\(aq in the CVS manual).
939 .SP
940 .IP "" 0
941 \fB-q\fR
942 .IP "" 2
943 Run quietly; do not print diagnostics.
944 .SP
945 .IP "" 0
946 \fB-s\fIstate\fB[:\fIrev\fB]\fR
947 .IP "" 2
948 Useful with \fBcvs\fR.  Set the state attribute of the
949 revision \fIrev\fR to \fIstate\fR.  If \fIrev\fR is a
950 branch number, assume the latest revision on that
951 branch.  If \fIrev\fR is omitted, assume the latest
952 revision on the default branch.  Any identifier is
953 acceptable for \fIstate\fR.  A useful set of states is
954 \fBExp\fR (for experimental), \fBStab\fR (for
955 stable), and \fBRel\fR (for released).  By default,
956 the state of a new revision is set to \fBExp\fR when
957 it is created.  The state is visible in the output from
958 \fIcvs log\fR (see node `log\(aq in the CVS manual), and in the
959 \fB$\fP\fPLog$\fR and \fB$\fP\fPState$\fR keywords
960 (see node `Keyword substitution\(aq in the CVS manual).  Note that \fBcvs\fR
961 uses the \fBdead\fR state for its own purposes; to
962 take a file to or from the \fBdead\fR state use
963 commands like \fBcvs remove\fR and \fBcvs add\fR, not
964 \fBcvs admin -s\fR.
965 .SP
966 .IP "" 0
967 \fB-t[\fIfile\fB]\fR
968 .IP "" 2
969 Useful with \fBcvs\fR.  Write descriptive text from the
970 contents of the named \fIfile\fR into the RCS file,
971 deleting the existing text.  The \fIfile\fR pathname
972 may not begin with \fB-\fR.  The descriptive text can be seen in the
973 output from \fBcvs log\fR (see node `log\(aq in the CVS manual).
974 There can be no space between \fB-t\fR and its argument.
975 .SP
976 If \fIfile\fR is omitted,
977 obtain the text from standard input, terminated by
978 end-of-file or by a line containing \fB.\fR by itself.
979 Prompt for the text if interaction is possible; see
980 \fB-I\fR.
981 .SP
982 .IP "" 0
983 \fB-t-\fIstring\fB\fR
984 .IP "" 2
985 Similar to \fB-t\fIfile\fB\fR. Write descriptive text
986 from the \fIstring\fR into the \fBrcs\fR file, deleting
987 the existing text.
988 There can be no space between \fB-t\fR and its argument.
989 .SP
990 .IP "" 0
991 \fB-U\fR
992 .IP "" 2
993 Set locking to non-strict.  Non-strict locking means
994 that the owner of a file need not lock a revision for
995 checkin.  For use with \fBcvs\fR, strict locking must be
996 set; see the discussion under the \fB-l\fR option
997 above.
998 .SP
999 .IP "" 0
1000 \fB-u[\fIrev\fB]\fR
1001 .IP "" 2
1002 See the option \fB-l\fR above, for a discussion of
1003 using this option with \fBcvs\fR.  Unlock the revision
1004 with number \fIrev\fR.  If a branch is given, unlock
1005 the latest revision on that branch.  If \fIrev\fR is
1006 omitted, remove the latest lock held by the caller.
1007 Normally, only the locker of a revision may unlock it;
1008 somebody else unlocking a revision breaks the lock.
1009 This causes the original locker to be sent a \fBcommit\fR
1010 notification (see node `Getting Notified\(aq in the CVS manual).
1011 There can be no space between \fB-u\fR and its argument.
1012 .SP
1013 .IP "" 0
1014 \fB-V\fIn\fB\fR
1015 .IP "" 2
1016 In previous versions of \fBcvs\fR, this option meant to
1017 write an \fBrcs\fR file which would be acceptable to
1018 \fBrcs\fR version \fIn\fR, but it is now obsolete and
1019 specifying it will produce an error.
1020 .SP
1021 .IP "" 0
1022 \fB-x\fIsuffixes\fB\fR
1023 .IP "" 2
1024 In previous versions of \fBcvs\fR, this was documented
1025 as a way of specifying the names of the \fBrcs\fR
1026 files.  However, \fBcvs\fR has always required that the
1027 \fBrcs\fR files used by \fBcvs\fR end in \fB,v\fR, so
1028 this option has never done anything useful.
1029 .SP
1030 .SP
1031 .SH "annotate"
1032 .SS "What revision modified each line of a file?"
1033 .IX "annotate (subcommand)"
1034 .SP
1035 .IP "\(bu" 2
1036 Synopsis: annotate [options] files\&...
1037 .IP "\(bu" 2
1038 Requires: repository.
1039 .IP "\(bu" 2
1040 Changes: nothing.
1041 .SP
1042 For each file in \fIfiles\fR, print the head revision
1043 of the trunk, together with information on the last
1044 modification for each line.  
1045 .SP
1046 .SH "annotate options"
1047 .SP
1048 These standard options are supported by \fBannotate\fR
1049 (see node `Common options\(aq in the CVS manual, for a complete description of
1050 them):
1051 .SP
1052 .IP "" 0
1053 \fB-l\fR
1054 .IP "" 2
1055 Local directory only, no recursion.
1056 .SP
1057 .IP "" 0
1058 \fB-R\fR
1059 .IP "" 2
1060 Process directories recursively.
1061 .SP
1062 .IP "" 0
1063 \fB-f\fR
1064 .IP "" 2
1065 Use head revision if tag/date not found.
1066 .SP
1067 .IP "" 0
1068 \fB-F\fR
1069 .IP "" 2
1070 Annotate binary files.
1071 .SP
1072 .IP "" 0
1073 \fB-r \fIrevision\fB\fR
1074 .IP "" 2
1075 Annotate file as of specified revision/tag.
1076 .SP
1077 .IP "" 0
1078 \fB-D \fIdate\fB\fR
1079 .IP "" 2
1080 Annotate file as of specified date.
1081 .SP
1082 .SH "annotate example"
1083 .SP
1084 For example:
1085 .SP
1086 .PD 0
1087 .SP
1088 .IP "" 2
1089 $ cvs annotate ssfile
1090 .IP "" 2
1091 Annotations for ssfile
1092 .IP "" 2
1093 ***************
1094 .IP "" 2
1095 1.1          (mary     27-Mar-96): ssfile line 1
1096 .IP "" 2
1097 1.2          (joe      28-Mar-96): ssfile line 2
1098
1099 .PD
1100 .IP "" 0
1101 .SP
1102 The file \fBssfile\fR currently contains two lines.
1103 The \fBssfile line 1\fR line was checked in by
1104 \fBmary\fR on March 27.  Then, on March 28, \fBjoe\fR
1105 added a line \fBssfile line 2\fR, without modifying
1106 the \fBssfile line 1\fR line.  This report doesn\(aqt
1107 tell you anything about lines which have been deleted
1108 or replaced; you need to use \fBcvs diff\fR for that
1109 (see node `diff\(aq in the CVS manual).
1110 .SP
1111 The options to \fBcvs annotate\fR are listed in
1112 see node `Invoking CVS\(aq in the CVS manual, and can be used to select the files
1113 and revisions to annotate.  The options are described
1114 in more detail there and in see node `Common options\(aq in the CVS manual.
1115 .SP
1116 .SH "checkout"
1117 .SS "Check out sources for editing"
1118 .IX "checkout (subcommand)"
1119 .IX "co (subcommand)"
1120 .SP
1121 .IP "\(bu" 2
1122 Synopsis: checkout [options] modules\&...
1123 .IP "\(bu" 2
1124 Requires: repository.
1125 .IP "\(bu" 2
1126 Changes: working directory.
1127 .IP "\(bu" 2
1128 Synonyms: co, get
1129 .SP
1130 Create or update a working directory containing copies of the
1131 source files specified by \fImodules\fR.  You must execute
1132 \fBcheckout\fR before using most of the other \fBcvs\fR
1133 commands, since most of them operate on your working
1134 directory.
1135 .SP
1136 The \fImodules\fR are either
1137 symbolic names for some
1138 collection of source directories and files, or paths to
1139 directories or files in the repository.  The symbolic
1140 names are defined in the \fBmodules\fR file.
1141 see node `modules\(aq in the CVS manual.
1142 .SP
1143 Depending on the modules you specify, \fBcheckout\fR may
1144 recursively create directories and populate them with
1145 the appropriate source files.  You can then edit these
1146 source files at any time (regardless of whether other
1147 software developers are editing their own copies of the
1148 sources); update them to include new changes applied by
1149 others to the source repository; or commit your work as
1150 a permanent change to the source repository.
1151 .SP
1152 Note that \fBcheckout\fR is used to create
1153 directories.  The top-level directory created is always
1154 added to the directory where \fBcheckout\fR is
1155 invoked, and usually has the same name as the specified
1156 module.  In the case of a module alias, the created
1157 sub-directory may have a different name, but you can be
1158 sure that it will be a sub-directory, and that
1159 \fBcheckout\fR will show the relative path leading to
1160 each file as it is extracted into your private work
1161 area (unless you specify the \fB-Q\fR global option).
1162 .SP
1163 The files created by \fBcheckout\fR are created
1164 read-write, unless the \fB-r\fR option to \fBcvs\fR
1165 (see node `Global options\(aq in the CVS manual) is specified, the
1166 \fBCVSREAD\fR environment variable is specified
1167 (see node `Environment variables\(aq in the CVS manual), or a watch is in
1168 effect for that file (see node `Watches\(aq in the CVS manual).
1169 .SP
1170 Note that running \fBcheckout\fR on a directory that was already
1171 built by a prior \fBcheckout\fR is also permitted.
1172 This is similar to specifying the \fB-d\fR option
1173 to the \fBupdate\fR command in the sense that new
1174 directories that have been created in the repository
1175 will appear in your work area.
1176 However, \fBcheckout\fR takes a module name whereas
1177 \fBupdate\fR takes a directory name.  Also
1178 to use \fBcheckout\fR this way it must be run from the
1179 top level directory (where you originally ran
1180 \fBcheckout\fR from), so before you run
1181 \fBcheckout\fR to update an existing directory, don\(aqt
1182 forget to change your directory to the top level
1183 directory.
1184 .SP
1185 For the output produced by the \fBcheckout\fR command
1186 see see node `update output\(aq in the CVS manual.
1187 .SP
1188 .SH "checkout options"
1189 .SP
1190 These standard options are supported by \fBcheckout\fR
1191 (see node `Common options\(aq in the CVS manual, for a complete description of
1192 them):
1193 .SP
1194 .IP "" 0
1195 \fB-D \fIdate\fB\fR
1196 .IP "" 2
1197 Use the most recent revision no later than \fIdate\fR.
1198 This option is sticky, and implies \fB-P\fR.  See
1199 see node `Sticky tags\(aq in the CVS manual, for more information on sticky tags/dates.
1200 .SP
1201 .IP "" 0
1202 \fB-f\fR
1203 .IP "" 2
1204 Only useful with the \fB-D \fIdate\fB\fR or \fB-r
1205 \fItag\fB\fR flags.  If no matching revision is found,
1206 retrieve the most recent revision (instead of ignoring
1207 the file).
1208 .SP
1209 .IP "" 0
1210 \fB-k \fIkflag\fB\fR
1211 .IP "" 2
1212 Process keywords according to \fIkflag\fR.  See
1213 see node `Keyword substitution\(aq in the CVS manual.
1214 This option is sticky; future updates of
1215 this file in this working directory will use the same
1216 \fIkflag\fR.  The \fBstatus\fR command can be viewed
1217 to see the sticky options.  See see node `Invoking CVS\(aq in the CVS manual, for
1218 more information on the \fBstatus\fR command.
1219 .SP
1220 .IP "" 0
1221 \fB-l\fR
1222 .IP "" 2
1223 Local; run only in current working directory.
1224 .SP
1225 .IP "" 0
1226 \fB-n\fR
1227 .IP "" 2
1228 Do not run any checkout program (as specified
1229 with the \fB-o\fR option in the modules file;
1230 see node `modules\(aq in the CVS manual).
1231 .SP
1232 .IP "" 0
1233 \fB-P\fR
1234 .IP "" 2
1235 Prune empty directories.  See see node `Moving directories\(aq in the CVS manual.
1236 .SP
1237 .IP "" 0
1238 \fB-p\fR
1239 .IP "" 2
1240 Pipe files to the standard output.
1241 .SP
1242 .IP "" 0
1243 \fB-R\fR
1244 .IP "" 2
1245 Checkout directories recursively.  This option is on by default.
1246 .SP
1247 .IP "" 0
1248 \fB-r \fItag\fB\fR
1249 .IP "" 2
1250 Use revision \fItag\fR.  This option is sticky, and implies \fB-P\fR.
1251 See see node `Sticky tags\(aq in the CVS manual, for more information on sticky tags/dates.
1252 .SP
1253 In addition to those, you can use these special command
1254 options with \fBcheckout\fR:
1255 .SP
1256 .IP "" 0
1257 \fB-A\fR
1258 .IP "" 2
1259 Reset any sticky tags, dates, or \fB-k\fR options.
1260 See see node `Sticky tags\(aq in the CVS manual, for more information on sticky tags/dates.
1261 .SP
1262 .IP "" 0
1263 \fB-c\fR
1264 .IP "" 2
1265 Copy the module file, sorted, to the standard output,
1266 instead of creating or modifying any files or
1267 directories in your working directory.
1268 .SP
1269 .IP "" 0
1270 \fB-d \fIdir\fB\fR
1271 .IP "" 2
1272 Create a directory called \fIdir\fR for the working
1273 files, instead of using the module name.  In general,
1274 using this flag is equivalent to using \fBmkdir
1275 \fIdir\fB; cd \fIdir\fB\fR followed by the checkout
1276 command without the \fB-d\fR flag.
1277 .SP
1278 There is an important exception, however.  It is very
1279 convenient when checking out a single item to have the
1280 output appear in a directory that doesn\(aqt contain empty
1281 intermediate directories.  In this case \fIonly\fR,
1282 \fBcvs\fR tries to \`\`shorten\(aq\(aq pathnames to avoid those empty
1283 directories.
1284 .SP
1285 For example, given a module \fBfoo\fR that contains
1286 the file \fBbar.c\fR, the command \fBcvs co -d dir
1287 foo\fR will create directory \fBdir\fR and place
1288 \fBbar.c\fR inside.  Similarly, given a module
1289 \fBbar\fR which has subdirectory \fBbaz\fR wherein
1290 there is a file \fBquux.c\fR, the command \fBcvs co
1291 -d dir bar/baz\fR will create directory \fBdir\fR and
1292 place \fBquux.c\fR inside.
1293 .SP
1294 Using the \fB-N\fR flag will defeat this behavior.
1295 Given the same module definitions above, \fBcvs co
1296 -N -d dir foo\fR will create directories \fBdir/foo\fR
1297 and place \fBbar.c\fR inside, while \fBcvs co -N -d
1298 dir bar/baz\fR will create directories \fBdir/bar/baz\fR
1299 and place \fBquux.c\fR inside.
1300 .SP
1301 .IP "" 0
1302 \fB-j \fItag\fB\fR
1303 .IP "" 2
1304 With two \fB-j\fR options, merge changes from the
1305 revision specified with the first \fB-j\fR option to
1306 the revision specified with the second \fBj\fR option,
1307 into the working directory.
1308 .SP
1309 With one \fB-j\fR option, merge changes from the
1310 ancestor revision to the revision specified with the
1311 \fB-j\fR option, into the working directory.  The
1312 ancestor revision is the common ancestor of the
1313 revision which the working directory is based on, and
1314 the revision specified in the \fB-j\fR option.
1315 .SP
1316 In addition, each -j option can contain an optional
1317 date specification which, when used with branches, can
1318 limit the chosen revision to one within a specific
1319 date.  An optional date is specified by adding a colon
1320 (:) to the tag:
1321 \fB-j\fISymbolic_Tag\fB:\fIDate_Specifier\fB\fR.
1322 .SP
1323 see node `Branching and merging\(aq in the CVS manual.
1324 .SP
1325 .IP "" 0
1326 \fB-N\fR
1327 .IP "" 2
1328 Only useful together with \fB-d \fIdir\fB\fR.  With
1329 this option, \fBcvs\fR will not \`\`shorten\(aq\(aq module paths
1330 in your working directory when you check out a single
1331 module.  See the \fB-d\fR flag for examples and a
1332 discussion.
1333 .SP
1334 .IP "" 0
1335 \fB-s\fR
1336 .IP "" 2
1337 Like \fB-c\fR, but include the status of all modules,
1338 and sort it by the status string.  see node `modules\(aq in the CVS manual, for
1339 info about the \fB-s\fR option that is used inside the
1340 modules file to set the module status.
1341 .SP
1342 .SH "checkout examples"
1343 .SP
1344 Get a copy of the module \fBtc\fR:
1345 .SP
1346 .PD 0
1347 .SP
1348 .IP "" 2
1349 $ cvs checkout tc
1350
1351 .PD
1352 .IP "" 0
1353 .SP
1354 Get a copy of the module \fBtc\fR as it looked one day
1355 ago:
1356 .SP
1357 .PD 0
1358 .SP
1359 .IP "" 2
1360 $ cvs checkout -D yesterday tc
1361
1362 .PD
1363 .IP "" 0
1364 .SP
1365 .SH "commit"
1366 .SS "Check files into the repository"
1367 .IX "commit (subcommand)"
1368 .SP
1369 .IP "\(bu" 2
1370 Synopsis: commit [-lnRf] [-m \(aqlog_message\(aq |
1371 -F file] [-r revision] [files\&...]
1372 .IP "\(bu" 2
1373 Requires: working directory, repository.
1374 .IP "\(bu" 2
1375 Changes: repository.
1376 .IP "\(bu" 2
1377 Synonym: ci
1378 .SP
1379 Use \fBcommit\fR when you want to incorporate changes
1380 from your working source files into the source
1381 repository.
1382 .SP
1383 If you don\(aqt specify particular files to commit, all of
1384 the files in your working current directory are
1385 examined.  \fBcommit\fR is careful to change in the
1386 repository only those files that you have really
1387 changed.  By default (or if you explicitly specify the
1388 \fB-R\fR option), files in subdirectories are also
1389 examined and committed if they have changed; you can
1390 use the \fB-l\fR option to limit \fBcommit\fR to the
1391 current directory only.
1392 .SP
1393 \fBcommit\fR verifies that the selected files are up
1394 to date with the current revisions in the source
1395 repository; it will notify you, and exit without
1396 committing, if any of the specified files must be made
1397 current first with \fBupdate\fR (see node `update\(aq in the CVS manual).
1398 \fBcommit\fR does not call the \fBupdate\fR command
1399 for you, but rather leaves that for you to do when the
1400 time is right.
1401 .SP
1402 When all is well, an editor is invoked to allow you to
1403 enter a log message that will be written to one or more
1404 logging programs (see node `modules\(aq in the CVS manual, and see node `loginfo\(aq in the CVS manual)
1405 and placed in the \fBrcs\fR file inside the
1406 repository.  This log message can be retrieved with the
1407 \fBlog\fR command; see see node `log\(aq in the CVS manual.  You can specify the
1408 log message on the command line with the \fB-m
1409 \fImessage\fB\fR option, and thus avoid the editor invocation,
1410 or use the \fB-F \fIfile\fB\fR option to specify
1411 that the argument file contains the log message.
1412 .SP
1413 .SH "commit options"
1414 .SP
1415 These standard options are supported by \fBcommit\fR
1416 (see node `Common options\(aq in the CVS manual, for a complete description of
1417 them):
1418 .SP
1419 .IP "" 0
1420 \fB-l\fR
1421 .IP "" 2
1422 Local; run only in current working directory.
1423 .SP
1424 .IP "" 0
1425 \fB-R\fR
1426 .IP "" 2
1427 Commit directories recursively.  This is on by default.
1428 .SP
1429 .IP "" 0
1430 \fB-r \fIrevision\fB\fR
1431 .IP "" 2
1432 Commit to \fIrevision\fR.  \fIrevision\fR must be
1433 either a branch, or a revision on the main trunk that
1434 is higher than any existing revision number
1435 (see node `Assigning revisions\(aq in the CVS manual).  You
1436 cannot commit to a specific revision on a branch.
1437 .SP
1438 \fBcommit\fR also supports these options:
1439 .SP
1440 .IP "" 0
1441 \fB-c\fR
1442 .IP "" 2
1443 Refuse to commit files unless the user has registered a valid edit on the
1444 file via \fBcvs edit\fR.  This is most useful when \fBcommit -c\fR
1445 and \fBedit -c\fR have been placed in all \fB.cvsrc\fR files.
1446 A commit can be forced anyways by either regestering an edit retroactively
1447 via \fBcvs edit\fR (no changes to the file will be lost) or using the
1448 \fB-f\fR option to commit.  Support for \fBcommit -c\fR requires both
1449 client and a server versions 1.12.10 or greater.
1450 .SP
1451 .IP "" 0
1452 \fB-F \fIfile\fB\fR
1453 .IP "" 2
1454 Read the log message from \fIfile\fR, instead
1455 of invoking an editor.
1456 .SP
1457 .IP "" 0
1458 \fB-f\fR
1459 .IP "" 2
1460 Note that this is not the standard behavior of
1461 the \fB-f\fR option as defined in see node `Common options\(aq in the CVS manual.
1462 .SP
1463 Force \fBcvs\fR to commit a new revision even if you haven\(aqt
1464 made any changes to the file.  As of \fBcvs\fR version 1.12.10,
1465 it also causes the \fB-c\fR option to be ignored.  If the current revision
1466 of \fIfile\fR is 1.7, then the following two commands
1467 are equivalent:
1468 .SP
1469 .PD 0
1470 .SP
1471 .IP "" 4
1472 $ cvs commit -f \fIfile\fR
1473 .IP "" 4
1474 $ cvs commit -r 1.8 \fIfile\fR
1475
1476 .PD
1477 .IP "" 2
1478 .SP
1479 The \fB-f\fR option disables recursion (i.e., it
1480 implies \fB-l\fR).  To force \fBcvs\fR to commit a new
1481 revision for all files in all subdirectories, you must
1482 use \fB-f -R\fR.
1483 .SP
1484 .IP "" 0
1485 \fB-m \fImessage\fB\fR
1486 .IP "" 2
1487 Use \fImessage\fR as the log message, instead of
1488 invoking an editor.
1489 .SP
1490 .SH "commit examples"
1491 .SP
1492 .SS "Committing to a branch"
1493 .SP
1494 You can commit to a branch revision (one that has an
1495 even number of dots) with the \fB-r\fR option.  To
1496 create a branch revision, use the \fB-b\fR option
1497 of the \fBrtag\fR or \fBtag\fR commands
1498 (see node `Branching and merging\(aq in the CVS manual).  Then, either \fBcheckout\fR or
1499 \fBupdate\fR can be used to base your sources on the
1500 newly created branch.  From that point on, all
1501 \fBcommit\fR changes made within these working sources
1502 will be automatically added to a branch revision,
1503 thereby not disturbing main-line development in any
1504 way.  For example, if you had to create a patch to the
1505 1.2 version of the product, even though the 2.0 version
1506 is already under development, you might do:
1507 .SP
1508 .PD 0
1509 .SP
1510 .IP "" 2
1511 $ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
1512 .IP "" 2
1513 $ cvs checkout -r FCS1_2_Patch product_module
1514 .IP "" 2
1515 $ cd product_module
1516 .IP "" 2
1517 [[ hack away ]]
1518 .IP "" 2
1519 $ cvs commit
1520
1521 .PD
1522 .IP "" 0
1523 .SP
1524 This works automatically since the \fB-r\fR option is
1525 sticky.
1526 .SP
1527 .SS "Creating the branch after editing"
1528 .SP
1529 Say you have been working on some extremely
1530 experimental software, based on whatever revision you
1531 happened to checkout last week.  If others in your
1532 group would like to work on this software with you, but
1533 without disturbing main-line development, you could
1534 commit your change to a new branch.  Others can then
1535 checkout your experimental stuff and utilize the full
1536 benefit of \fBcvs\fR conflict resolution.  The scenario might
1537 look like:
1538 .SP
1539 .PD 0
1540 .SP
1541 .IP "" 2
1542 [[ hacked sources are present ]]
1543 .IP "" 2
1544 $ cvs tag -b EXPR1
1545 .IP "" 2
1546 $ cvs update -r EXPR1
1547 .IP "" 2
1548 $ cvs commit
1549
1550 .PD
1551 .IP "" 0
1552 .SP
1553 The \fBupdate\fR command will make the \fB-r
1554 EXPR1\fR option sticky on all files.  Note that your
1555 changes to the files will never be removed by the
1556 \fBupdate\fR command.  The \fBcommit\fR will
1557 automatically commit to the correct branch, because the
1558 \fB-r\fR is sticky.  You could also do like this:
1559 .SP
1560 .PD 0
1561 .SP
1562 .IP "" 2
1563 [[ hacked sources are present ]]
1564 .IP "" 2
1565 $ cvs tag -b EXPR1
1566 .IP "" 2
1567 $ cvs commit -r EXPR1
1568
1569 .PD
1570 .IP "" 0
1571 .SP
1572 but then, only those files that were changed by you
1573 will have the \fB-r EXPR1\fR sticky flag.  If you hack
1574 away, and commit without specifying the \fB-r EXPR1\fR
1575 flag, some files may accidentally end up on the main
1576 trunk.
1577 .SP
1578 To work with you on the experimental change, others
1579 would simply do
1580 .SP
1581 .PD 0
1582 .SP
1583 .IP "" 2
1584 $ cvs checkout -r EXPR1 whatever_module
1585
1586 .PD
1587 .IP "" 0
1588 .SP
1589 .SH "diff"
1590 .SS "Show differences between revisions"
1591 .IX "diff (subcommand)"
1592 .SP
1593 .IP "\(bu" 2
1594 Synopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r rev2 |  -D date2]] [files\&...]
1595 .IP "\(bu" 2
1596 Requires: working directory, repository.
1597 .IP "\(bu" 2
1598 Changes: nothing.
1599 .SP
1600 The \fBdiff\fR command is used to compare different
1601 revisions of files.  The default action is to compare
1602 your working files with the revisions they were based
1603 on, and report any differences that are found.
1604 .SP
1605 If any file names are given, only those files are
1606 compared.  If any directories are given, all files
1607 under them will be compared.
1608 .SP
1609 The exit status for diff is different than for other
1610 \fBcvs\fR commands; for details see node `Exit status\(aq in the CVS manual.
1611 .SP
1612 .SH "diff options"
1613 .SP
1614 These standard options are supported by \fBdiff\fR
1615 (see node `Common options\(aq in the CVS manual, for a complete description of
1616 them):
1617 .SP
1618 .IP "" 0
1619 \fB-D \fIdate\fB\fR
1620 .IP "" 2
1621 Use the most recent revision no later than \fIdate\fR.
1622 See \fB-r\fR for how this affects the comparison.
1623 .SP
1624 .IP "" 0
1625 \fB-k \fIkflag\fB\fR
1626 .IP "" 2
1627 Process keywords according to \fIkflag\fR.  See
1628 see node `Keyword substitution\(aq in the CVS manual.
1629 .SP
1630 .IP "" 0
1631 \fB-l\fR
1632 .IP "" 2
1633 Local; run only in current working directory.
1634 .SP
1635 .IP "" 0
1636 \fB-R\fR
1637 .IP "" 2
1638 Examine directories recursively.  This option is on by
1639 default.
1640 .SP
1641 .IP "" 0
1642 \fB-r \fItag\fB\fR
1643 .IP "" 2
1644 Compare with revision \fItag\fR.  Zero, one or two
1645 \fB-r\fR options can be present.  With no \fB-r\fR
1646 option, the working file will be compared with the
1647 revision it was based on.  With one \fB-r\fR, that
1648 revision will be compared to your current working file.
1649 With two \fB-r\fR options those two revisions will be
1650 compared (and your working file will not affect the
1651 outcome in any way).
1652 .SP
1653 One or both \fB-r\fR options can be replaced by a
1654 \fB-D \fIdate\fB\fR option, described above.
1655 .SP
1656 The following options specify the format of the
1657 output.  They have the same meaning as in GNU diff.
1658 Most options have two equivalent names, one of which is a single letter
1659 preceded by \fB-\fR, and the other of which is a long name preceded by
1660 \fB--\fR.
1661 .SP
1662 .IP "" 0
1663 \fB-\fIlines\fB\fR
1664 .IP "" 2
1665 Show \fIlines\fR (an integer) lines of context.  This option does not
1666 specify an output format by itself; it has no effect unless it is
1667 combined with \fB-c\fR or \fB-u\fR.  This option is obsolete.  For proper
1668 operation, \fBpatch\fR typically needs at least two lines of context.
1669 .SP
1670 .IP "" 0
1671 \fB-a\fR
1672 .IP "" 2
1673 Treat all files as text and compare them line-by-line, even if they
1674 do not seem to be text.
1675 .SP
1676 .IP "" 0
1677 \fB-b\fR
1678 .IP "" 2
1679 Ignore trailing white space and consider all other sequences of one or
1680 more white space characters to be equivalent.
1681 .SP
1682 .IP "" 0
1683 \fB-B\fR
1684 .IP "" 2
1685 Ignore changes that just insert or delete blank lines.
1686 .SP
1687 .IP "" 0
1688 \fB--binary\fR
1689 .IP "" 2
1690 Read and write data in binary mode.
1691 .SP
1692 .IP "" 0
1693 \fB--brief\fR
1694 .IP "" 2
1695 Report only whether the files differ, not the details of the
1696 differences.
1697 .SP
1698 .IP "" 0
1699 \fB-c\fR
1700 .IP "" 2
1701 Use the context output format.
1702 .SP
1703 .IP "" 0
1704 \fB-C \fIlines\fB\fR
1705 .IP "" 2
1706 .IP "" 0
1707 \fB--context\fR[\fB=\fIlines\fB\fR]\fB\fR
1708 .IP "" 2
1709 Use the context output format, showing \fIlines\fR (an integer) lines of
1710 context, or three if \fIlines\fR is not given.
1711 For proper operation, \fBpatch\fR typically needs at least two lines of
1712 context.
1713 .SP
1714 .IP "" 0
1715 \fB--changed-group-format=\fIformat\fB\fR
1716 .IP "" 2
1717 Use \fIformat\fR to output a line group containing differing lines from
1718 both files in if-then-else format.  see node `Line group formats\(aq in the CVS manual.
1719 .SP
1720 .IP "" 0
1721 \fB-d\fR
1722 .IP "" 2
1723 Change the algorithm to perhaps find a smaller set of changes.  This makes
1724 \fBdiff\fR slower (sometimes much slower).
1725 .SP
1726 .IP "" 0
1727 \fB-e\fR
1728 .IP "" 2
1729 .IP "" 0
1730 \fB--ed\fR
1731 .IP "" 2
1732 Make output that is a valid \fBed\fR script.
1733 .SP
1734 .IP "" 0
1735 \fB--expand-tabs\fR
1736 .IP "" 2
1737 Expand tabs to spaces in the output, to preserve the alignment of tabs
1738 in the input files.
1739 .SP
1740 .IP "" 0
1741 \fB-f\fR
1742 .IP "" 2
1743 Make output that looks vaguely like an \fBed\fR script but has changes
1744 in the order they appear in the file.
1745 .SP
1746 .IP "" 0
1747 \fB-F \fIregexp\fB\fR
1748 .IP "" 2
1749 In context and unified format, for each hunk of differences, show some
1750 of the last preceding line that matches \fIregexp\fR.
1751 .SP
1752 .IP "" 0
1753 \fB--forward-ed\fR
1754 .IP "" 2
1755 Make output that looks vaguely like an \fBed\fR script but has changes
1756 in the order they appear in the file.
1757 .SP
1758 .IP "" 0
1759 \fB-H\fR
1760 .IP "" 2
1761 Use heuristics to speed handling of large files that have numerous
1762 scattered small changes.
1763 .SP
1764 .IP "" 0
1765 \fB--horizon-lines=\fIlines\fB\fR
1766 .IP "" 2
1767 Do not discard the last \fIlines\fR lines of the common prefix
1768 and the first \fIlines\fR lines of the common suffix.
1769 .SP
1770 .IP "" 0
1771 \fB-i\fR
1772 .IP "" 2
1773 Ignore changes in case; consider upper- and lower-case letters
1774 equivalent.
1775 .SP
1776 .IP "" 0
1777 \fB-I \fIregexp\fB\fR
1778 .IP "" 2
1779 Ignore changes that just insert or delete lines that match \fIregexp\fR.
1780 .SP
1781 .IP "" 0
1782 \fB--ifdef=\fIname\fB\fR
1783 .IP "" 2
1784 Make merged if-then-else output using \fIname\fR.
1785 .SP
1786 .IP "" 0
1787 \fB--ignore-all-space\fR
1788 .IP "" 2
1789 Ignore white space when comparing lines.
1790 .SP
1791 .IP "" 0
1792 \fB--ignore-blank-lines\fR
1793 .IP "" 2
1794 Ignore changes that just insert or delete blank lines.
1795 .SP
1796 .IP "" 0
1797 \fB--ignore-case\fR
1798 .IP "" 2
1799 Ignore changes in case; consider upper- and lower-case to be the same.
1800 .SP
1801 .IP "" 0
1802 \fB--ignore-matching-lines=\fIregexp\fB\fR
1803 .IP "" 2
1804 Ignore changes that just insert or delete lines that match \fIregexp\fR.
1805 .SP
1806 .IP "" 0
1807 \fB--ignore-space-change\fR
1808 .IP "" 2
1809 Ignore trailing white space and consider all other sequences of one or
1810 more white space characters to be equivalent.
1811 .SP
1812 .IP "" 0
1813 \fB--initial-tab\fR
1814 .IP "" 2
1815 Output a tab rather than a space before the text of a line in normal or
1816 context format.  This causes the alignment of tabs in the line to look
1817 normal.
1818 .SP
1819 .IP "" 0
1820 \fB-L \fIlabel\fB\fR
1821 .IP "" 2
1822 Use \fIlabel\fR instead of the file name in the context format
1823 and unified format headers.
1824 .SP
1825 .IP "" 0
1826 \fB--label=\fIlabel\fB\fR
1827 .IP "" 2
1828 Use \fIlabel\fR instead of the file name in the context format
1829 and unified format headers.
1830 .SP
1831 .IP "" 0
1832 \fB--left-column\fR
1833 .IP "" 2
1834 Print only the left column of two common lines in side by side format.
1835 .SP
1836 .IP "" 0
1837 \fB--line-format=\fIformat\fB\fR
1838 .IP "" 2
1839 Use \fIformat\fR to output all input lines in if-then-else format.
1840 see node `Line formats\(aq in the CVS manual.
1841 .SP
1842 .IP "" 0
1843 \fB--minimal\fR
1844 .IP "" 2
1845 Change the algorithm to perhaps find a smaller set of changes.  This
1846 makes \fBdiff\fR slower (sometimes much slower).
1847 .SP
1848 .IP "" 0
1849 \fB-n\fR
1850 .IP "" 2
1851 Output RCS-format diffs; like \fB-f\fR except that each command
1852 specifies the number of lines affected.
1853 .SP
1854 .IP "" 0
1855 \fB-N\fR
1856 .IP "" 2
1857 .IP "" 0
1858 \fB--new-file\fR
1859 .IP "" 2
1860 In directory comparison, if a file is found in only one directory,
1861 treat it as present but empty in the other directory.
1862 .SP
1863 .IP "" 0
1864 \fB--new-group-format=\fIformat\fB\fR
1865 .IP "" 2
1866 Use \fIformat\fR to output a group of lines taken from just the second
1867 file in if-then-else format.  see node `Line group formats\(aq in the CVS manual.
1868 .SP
1869 .IP "" 0
1870 \fB--new-line-format=\fIformat\fB\fR
1871 .IP "" 2
1872 Use \fIformat\fR to output a line taken from just the second file in
1873 if-then-else format.  see node `Line formats\(aq in the CVS manual.
1874 .SP
1875 .IP "" 0
1876 \fB--old-group-format=\fIformat\fB\fR
1877 .IP "" 2
1878 Use \fIformat\fR to output a group of lines taken from just the first
1879 file in if-then-else format.  see node `Line group formats\(aq in the CVS manual.
1880 .SP
1881 .IP "" 0
1882 \fB--old-line-format=\fIformat\fB\fR
1883 .IP "" 2
1884 Use \fIformat\fR to output a line taken from just the first file in
1885 if-then-else format.  see node `Line formats\(aq in the CVS manual.
1886 .SP
1887 .IP "" 0
1888 \fB-p\fR
1889 .IP "" 2
1890 Show which C function each change is in.
1891 .SP
1892 .IP "" 0
1893 \fB--rcs\fR
1894 .IP "" 2
1895 Output RCS-format diffs; like \fB-f\fR except that each command
1896 specifies the number of lines affected.
1897 .SP
1898 .IP "" 0
1899 \fB--report-identical-files\fR
1900 .IP "" 2
1901 .IP "" 0
1902 \fB-s\fR
1903 .IP "" 2
1904 Report when two files are the same.
1905 .SP
1906 .IP "" 0
1907 \fB--show-c-function\fR
1908 .IP "" 2
1909 Show which C function each change is in.
1910 .SP
1911 .IP "" 0
1912 \fB--show-function-line=\fIregexp\fB\fR
1913 .IP "" 2
1914 In context and unified format, for each hunk of differences, show some
1915 of the last preceding line that matches \fIregexp\fR.
1916 .SP
1917 .IP "" 0
1918 \fB--side-by-side\fR
1919 .IP "" 2
1920 Use the side by side output format.
1921 .SP
1922 .IP "" 0
1923 \fB--speed-large-files\fR
1924 .IP "" 2
1925 Use heuristics to speed handling of large files that have numerous
1926 scattered small changes.
1927 .SP
1928 .IP "" 0
1929 \fB--suppress-common-lines\fR
1930 .IP "" 2
1931 Do not print common lines in side by side format.
1932 .SP
1933 .IP "" 0
1934 \fB-t\fR
1935 .IP "" 2
1936 Expand tabs to spaces in the output, to preserve the alignment of tabs
1937 in the input files.
1938 .SP
1939 .IP "" 0
1940 \fB-T\fR
1941 .IP "" 2
1942 Output a tab rather than a space before the text of a line in normal or
1943 context format.  This causes the alignment of tabs in the line to look
1944 normal.
1945 .SP
1946 .IP "" 0
1947 \fB--text\fR
1948 .IP "" 2
1949 Treat all files as text and compare them line-by-line, even if they
1950 do not appear to be text.
1951 .SP
1952 .IP "" 0
1953 \fB-u\fR
1954 .IP "" 2
1955 Use the unified output format.
1956 .SP
1957 .IP "" 0
1958 \fB--unchanged-group-format=\fIformat\fB\fR
1959 .IP "" 2
1960 Use \fIformat\fR to output a group of common lines taken from both files
1961 in if-then-else format.  see node `Line group formats\(aq in the CVS manual.
1962 .SP
1963 .IP "" 0
1964 \fB--unchanged-line-format=\fIformat\fB\fR
1965 .IP "" 2
1966 Use \fIformat\fR to output a line common to both files in if-then-else
1967 format.  see node `Line formats\(aq in the CVS manual.
1968 .SP
1969 .IP "" 0
1970 \fB-U \fIlines\fB\fR
1971 .IP "" 2
1972 .IP "" 0
1973 \fB--unified\fR[\fB=\fIlines\fB\fR]\fB\fR
1974 .IP "" 2
1975 Use the unified output format, showing \fIlines\fR (an integer) lines of
1976 context, or three if \fIlines\fR is not given.
1977 For proper operation, \fBpatch\fR typically needs at least two lines of
1978 context.
1979 .SP
1980 .IP "" 0
1981 \fB-w\fR
1982 .IP "" 2
1983 Ignore white space when comparing lines.
1984 .SP
1985 .IP "" 0
1986 \fB-W \fIcolumns\fB\fR
1987 .IP "" 2
1988 .IP "" 0
1989 \fB--width=\fIcolumns\fB\fR
1990 .IP "" 2
1991 Use an output width of \fIcolumns\fR in side by side format.
1992 .SP
1993 .IP "" 0
1994 \fB-y\fR
1995 .IP "" 2
1996 Use the side by side output format.
1997 .SP
1998 .SH "Line group formats"
1999 .SP
2000 Line group formats let you specify formats suitable for many
2001 applications that allow if-then-else input, including programming
2002 languages and text formatting languages.  A line group format specifies
2003 the output format for a contiguous group of similar lines.
2004 .SP
2005 For example, the following command compares the TeX file \fBmyfile\fR
2006 with the original version from the repository,
2007 and outputs a merged file in which old regions are
2008 surrounded by \fB\\begin{em}\fR-\fB\\end{em}\fR lines, and new
2009 regions are surrounded by \fB\\begin{bf}\fR-\fB\\end{bf}\fR lines.
2010 .SP
2011 .PD 0
2012 .SP
2013 .IP "" 2
2014 cvs diff \\
2015 .IP "" 2
2016    --old-group-format=\(aq\\begin{em}
2017 .IP "" 2
2018 %<\\end{em}
2019 .IP "" 2
2020 \(aq \\
2021 .IP "" 2
2022    --new-group-format=\(aq\\begin{bf}
2023 .IP "" 2
2024 %>\\end{bf}
2025 .IP "" 2
2026 \(aq \\
2027 .IP "" 2
2028    myfile
2029
2030 .PD
2031 .IP "" 0
2032 .SP
2033 The following command is equivalent to the above example, but it is a
2034 little more verbose, because it spells out the default line group formats.
2035 .SP
2036 .PD 0
2037 .SP
2038 .IP "" 2
2039 cvs diff \\
2040 .IP "" 2
2041    --old-group-format=\(aq\\begin{em}
2042 .IP "" 2
2043 %<\\end{em}
2044 .IP "" 2
2045 \(aq \\
2046 .IP "" 2
2047    --new-group-format=\(aq\\begin{bf}
2048 .IP "" 2
2049 %>\\end{bf}
2050 .IP "" 2
2051 \(aq \\
2052 .IP "" 2
2053    --unchanged-group-format=\(aq%=\(aq \\
2054 .IP "" 2
2055    --changed-group-format=\(aq\\begin{em}
2056 .IP "" 2
2057 %<\\end{em}
2058 .IP "" 2
2059 \\begin{bf}
2060 .IP "" 2
2061 %>\\end{bf}
2062 .IP "" 2
2063 \(aq \\
2064 .IP "" 2
2065    myfile
2066
2067 .PD
2068 .IP "" 0
2069 .SP
2070 Here is a more advanced example, which outputs a diff listing with
2071 headers containing line numbers in a \`\`plain English\(aq\(aq style.
2072 .SP
2073 .PD 0
2074 .SP
2075 .IP "" 2
2076 cvs diff \\
2077 .IP "" 2
2078    --unchanged-group-format=\(aq\(aq \\
2079 .IP "" 2
2080    --old-group-format=\(aq-------- %dn line%(n=1?:s) deleted at %df:
2081 .IP "" 2
2082 %<\(aq \\
2083 .IP "" 2
2084    --new-group-format=\(aq-------- %dN line%(N=1?:s) added after %de:
2085 .IP "" 2
2086 %>\(aq \\
2087 .IP "" 2
2088    --changed-group-format=\(aq-------- %dn line%(n=1?:s) changed at %df:
2089 .IP "" 2
2090 %<-------- to:
2091 .IP "" 2
2092 %>\(aq \\
2093 .IP "" 2
2094    myfile
2095
2096 .PD
2097 .IP "" 0
2098 .SP
2099 To specify a line group format, use one of the options
2100 listed below.  You can specify up to four line group formats, one for
2101 each kind of line group.  You should quote \fIformat\fR, because it
2102 typically contains shell metacharacters.
2103 .SP
2104 .IP "" 0
2105 \fB--old-group-format=\fIformat\fB\fR
2106 .IP "" 2
2107 These line groups are hunks containing only lines from the first file.
2108 The default old group format is the same as the changed group format if
2109 it is specified; otherwise it is a format that outputs the line group as-is.
2110 .SP
2111 .IP "" 0
2112 \fB--new-group-format=\fIformat\fB\fR
2113 .IP "" 2
2114 These line groups are hunks containing only lines from the second
2115 file.  The default new group format is same as the changed group
2116 format if it is specified; otherwise it is a format that outputs the
2117 line group as-is.
2118 .SP
2119 .IP "" 0
2120 \fB--changed-group-format=\fIformat\fB\fR
2121 .IP "" 2
2122 These line groups are hunks containing lines from both files.  The
2123 default changed group format is the concatenation of the old and new
2124 group formats.
2125 .SP
2126 .IP "" 0
2127 \fB--unchanged-group-format=\fIformat\fB\fR
2128 .IP "" 2
2129 These line groups contain lines common to both files.  The default
2130 unchanged group format is a format that outputs the line group as-is.
2131 .SP
2132 In a line group format, ordinary characters represent themselves;
2133 conversion specifications start with \fB%\fR and have one of the
2134 following forms.
2135 .SP
2136 .IP "" 0
2137 \fB%<\fR
2138 .IP "" 2
2139 stands for the lines from the first file, including the trailing newline.
2140 Each line is formatted according to the old line format (see node `Line formats\(aq in the CVS manual).
2141 .SP
2142 .IP "" 0
2143 \fB%>\fR
2144 .IP "" 2
2145 stands for the lines from the second file, including the trailing newline.
2146 Each line is formatted according to the new line format.
2147 .SP
2148 .IP "" 0
2149 \fB%=\fR
2150 .IP "" 2
2151 stands for the lines common to both files, including the trailing newline.
2152 Each line is formatted according to the unchanged line format.
2153 .SP
2154 .IP "" 0
2155 \fB%%\fR
2156 .IP "" 2
2157 stands for \fB%\fR.
2158 .SP
2159 .IP "" 0
2160 \fB%c\(aq\fIC\fB\(aq\fR
2161 .IP "" 2
2162 where \fIC\fR is a single character, stands for \fIC\fR.
2163 \fIC\fR may not be a backslash or an apostrophe.
2164 For example, \fB%c\(aq:\(aq\fR stands for a colon, even inside
2165 the then-part of an if-then-else format, which a colon would
2166 normally terminate.
2167 .SP
2168 .IP "" 0
2169 \fB%c\(aq\\\fIO\fB\(aq\fR
2170 .IP "" 2
2171 where \fIO\fR is a string of 1, 2, or 3 octal digits,
2172 stands for the character with octal code \fIO\fR.
2173 For example, \fB%c\(aq\\0\(aq\fR stands for a null character.
2174 .SP
2175 .IP "" 0
2176 \fB\fIF\fB\fIn\fB\fR
2177 .IP "" 2
2178 where \fIF\fR is a \fBprintf\fR conversion specification and \fIn\fR is one
2179 of the following letters, stands for \fIn\fR\(aqs value formatted with \fIF\fR.
2180 .SP
2181 .IP "" 2
2182 \fBe\fR
2183 .IP "" 4
2184 The line number of the line just before the group in the old file.
2185 .SP
2186 .IP "" 2
2187 \fBf\fR
2188 .IP "" 4
2189 The line number of the first line in the group in the old file;
2190 equals \fIe\fR + 1.
2191 .SP
2192 .IP "" 2
2193 \fBl\fR
2194 .IP "" 4
2195 The line number of the last line in the group in the old file.
2196 .SP
2197 .IP "" 2
2198 \fBm\fR
2199 .IP "" 4
2200 The line number of the line just after the group in the old file;
2201 equals \fIl\fR + 1.
2202 .SP
2203 .IP "" 2
2204 \fBn\fR
2205 .IP "" 4
2206 The number of lines in the group in the old file; equals \fIl\fR - \fIf\fR + 1.
2207 .SP
2208 .IP "" 2
2209 \fBE, F, L, M, N\fR
2210 .IP "" 4
2211 Likewise, for lines in the new file.
2212 .SP
2213 .SP
2214 The \fBprintf\fR conversion specification can be \fB%d\fR,
2215 \fB%o\fR, \fB%x\fR, or \fB%X\fR, specifying decimal, octal,
2216 lower case hexadecimal, or upper case hexadecimal output
2217 respectively.  After the \fB%\fR the following options can appear in
2218 sequence: a \fB-\fR specifying left-justification; an integer
2219 specifying the minimum field width; and a period followed by an
2220 optional integer specifying the minimum number of digits.
2221 For example, \fB%5dN\fR prints the number of new lines in the group
2222 in a field of width 5 characters, using the \fBprintf\fR format \fB"%5d"\fR.
2223 .SP
2224 .IP "" 0
2225 \fB(\fIA\fB=\fIB\fB?\fIT\fB:\fIE\fB)\fR
2226 .IP "" 2
2227 If \fIA\fR equals \fIB\fR then \fIT\fR else \fIE\fR.
2228 \fIA\fR and \fIB\fR are each either a decimal constant
2229 or a single letter interpreted as above.
2230 This format spec is equivalent to \fIT\fR if
2231 \fIA\fR\(aqs value equals \fIB\fR\(aqs; otherwise it is equivalent to \fIE\fR.
2232 .SP
2233 For example, \fB%(N=0?no:%dN) line%(N=1?:s)\fR is equivalent to
2234 \fBno lines\fR if \fIN\fR (the number of lines in the group in the
2235 new file) is 0, to \fB1 line\fR if \fIN\fR is 1, and to \fB%dN lines\fR
2236 otherwise.
2237 .SP
2238 .SH "Line formats"
2239 .SP
2240 Line formats control how each line taken from an input file is
2241 output as part of a line group in if-then-else format.
2242 .SP
2243 For example, the following command outputs text with a one-column
2244 change indicator to the left of the text.  The first column of output
2245 is \fB-\fR for deleted lines, \fB|\fR for added lines, and a space
2246 for unchanged lines.  The formats contain newline characters where
2247 newlines are desired on output.
2248 .SP
2249 .PD 0
2250 .SP
2251 .IP "" 2
2252 cvs diff \\
2253 .IP "" 2
2254    --old-line-format=\(aq-%l
2255 .IP "" 2
2256 \(aq \\
2257 .IP "" 2
2258    --new-line-format=\(aq|%l
2259 .IP "" 2
2260 \(aq \\
2261 .IP "" 2
2262    --unchanged-line-format=\(aq %l
2263 .IP "" 2
2264 \(aq \\
2265 .IP "" 2
2266    myfile
2267
2268 .PD
2269 .IP "" 0
2270 .SP
2271 To specify a line format, use one of the following options.  You should
2272 quote \fIformat\fR, since it often contains shell metacharacters.
2273 .SP
2274 .IP "" 0
2275 \fB--old-line-format=\fIformat\fB\fR
2276 .IP "" 2
2277 formats lines just from the first file.
2278 .SP
2279 .IP "" 0
2280 \fB--new-line-format=\fIformat\fB\fR
2281 .IP "" 2
2282 formats lines just from the second file.
2283 .SP
2284 .IP "" 0
2285 \fB--unchanged-line-format=\fIformat\fB\fR
2286 .IP "" 2
2287 formats lines common to both files.
2288 .SP
2289 .IP "" 0
2290 \fB--line-format=\fIformat\fB\fR
2291 .IP "" 2
2292 formats all lines; in effect, it sets all three above options simultaneously.
2293 .SP
2294 In a line format, ordinary characters represent themselves;
2295 conversion specifications start with \fB%\fR and have one of the
2296 following forms.
2297 .SP
2298 .IP "" 0
2299 \fB%l\fR
2300 .IP "" 2
2301 stands for the contents of the line, not counting its trailing
2302 newline (if any).  This format ignores whether the line is incomplete.
2303 .SP
2304 .IP "" 0
2305 \fB%L\fR
2306 .IP "" 2
2307 stands for the contents of the line, including its trailing newline
2308 (if any).  If a line is incomplete, this format preserves its
2309 incompleteness.
2310 .SP
2311 .IP "" 0
2312 \fB%%\fR
2313 .IP "" 2
2314 stands for \fB%\fR.
2315 .SP
2316 .IP "" 0
2317 \fB%c\(aq\fIC\fB\(aq\fR
2318 .IP "" 2
2319 where \fIC\fR is a single character, stands for \fIC\fR.
2320 \fIC\fR may not be a backslash or an apostrophe.
2321 For example, \fB%c\(aq:\(aq\fR stands for a colon.
2322 .SP
2323 .IP "" 0
2324 \fB%c\(aq\\\fIO\fB\(aq\fR
2325 .IP "" 2
2326 where \fIO\fR is a string of 1, 2, or 3 octal digits,
2327 stands for the character with octal code \fIO\fR.
2328 For example, \fB%c\(aq\\0\(aq\fR stands for a null character.
2329 .SP
2330 .IP "" 0
2331 \fB\fIF\fBn\fR
2332 .IP "" 2
2333 where \fIF\fR is a \fBprintf\fR conversion specification,
2334 stands for the line number formatted with \fIF\fR.
2335 For example, \fB%.5dn\fR prints the line number using the
2336 \fBprintf\fR format \fB"%.5d"\fR.  see node `Line group formats\(aq in the CVS manual, for
2337 more about printf conversion specifications.
2338 .SP
2339 .SP
2340 The default line format is \fB%l\fR followed by a newline character.
2341 .SP
2342 If the input contains tab characters and it is important that they line
2343 up on output, you should ensure that \fB%l\fR or \fB%L\fR in a line
2344 format is just after a tab stop (e.g. by preceding \fB%l\fR or
2345 \fB%L\fR with a tab character), or you should use the \fB-t\fR or
2346 \fB--expand-tabs\fR option.
2347 .SP
2348 Taken together, the line and line group formats let you specify many
2349 different formats.  For example, the following command uses a format
2350 similar to \fBdiff\fR\(aqs normal format.  You can tailor this command
2351 to get fine control over \fBdiff\fR\(aqs output.
2352 .SP
2353 .PD 0
2354 .SP
2355 .IP "" 2
2356 cvs diff \\
2357 .IP "" 2
2358    --old-line-format=\(aq< %l
2359 .IP "" 2
2360 \(aq \\
2361 .IP "" 2
2362    --new-line-format=\(aq> %l
2363 .IP "" 2
2364 \(aq \\
2365 .IP "" 2
2366    --old-group-format=\(aq%df%(f=l?:,%dl)d%dE
2367 .IP "" 2
2368 %<\(aq \\
2369 .IP "" 2
2370    --new-group-format=\(aq%dea%dF%(F=L?:,%dL)
2371 .IP "" 2
2372 %>\(aq \\
2373 .IP "" 2
2374    --changed-group-format=\(aq%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
2375 .IP "" 2
2376 %<\(em
2377 .IP "" 2
2378 %>\(aq \\
2379 .IP "" 2
2380    --unchanged-group-format=\(aq\(aq \\
2381 .IP "" 2
2382    myfile
2383
2384 .PD
2385 .IP "" 0
2386 .SP
2387 .SH "diff examples"
2388 .SP
2389 The following line produces a Unidiff (\fB-u\fR flag)
2390 between revision 1.14 and 1.19 of
2391 \fBbackend.c\fR.  Due to the \fB-kk\fR flag no
2392 keywords are substituted, so differences that only depend
2393 on keyword substitution are ignored.
2394 .SP
2395 .PD 0
2396 .SP
2397 .IP "" 2
2398 $ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
2399
2400 .PD
2401 .IP "" 0
2402 .SP
2403 Suppose the experimental branch EXPR1 was based on a
2404 set of files tagged RELEASE_1_0.  To see what has
2405 happened on that branch, the following can be used:
2406 .SP
2407 .PD 0
2408 .SP
2409 .IP "" 2
2410 $ cvs diff -r RELEASE_1_0 -r EXPR1
2411
2412 .PD
2413 .IP "" 0
2414 .SP
2415 A command like this can be used to produce a context
2416 diff between two releases:
2417 .SP
2418 .PD 0
2419 .SP
2420 .IP "" 2
2421 $ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
2422
2423 .PD
2424 .IP "" 0
2425 .SP
2426 If you are maintaining ChangeLogs, a command like the following
2427 just before you commit your changes may help you write
2428 the ChangeLog entry.  All local modifications that have
2429 not yet been committed will be printed.
2430 .SP
2431 .PD 0
2432 .SP
2433 .IP "" 2
2434 $ cvs diff -u | less
2435
2436 .PD
2437 .IP "" 0
2438 .SP
2439 .SH "export"
2440 .SS "Export sources from CVS, similar to checkout"
2441 .IX "export (subcommand)"
2442 .SP
2443 .IP "\(bu" 2
2444 Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module\&...
2445 .IP "\(bu" 2
2446 Requires: repository.
2447 .IP "\(bu" 2
2448 Changes: current directory.
2449 .SP
2450 This command is a variant of \fBcheckout\fR; use it
2451 when you want a copy of the source for module without
2452 the \fBcvs\fR administrative directories.  For example, you
2453 might use \fBexport\fR to prepare source for shipment
2454 off-site.  This command requires that you specify a
2455 date or tag (with \fB-D\fR or \fB-r\fR), so that you
2456 can count on reproducing the source you ship to others
2457 (and thus it always prunes empty directories).
2458 .SP
2459 One often would like to use \fB-kv\fR with \fBcvs
2460 export\fR.  This causes any keywords to be
2461 expanded such that an import done at some other site
2462 will not lose the keyword revision information.  But be
2463 aware that doesn\(aqt handle an export containing binary
2464 files correctly.  Also be aware that after having used
2465 \fB-kv\fR, one can no longer use the \fBident\fR
2466 command (which is part of the \fBrcs\fR suite\(emsee
2467 ident(1)) which looks for keyword strings.  If
2468 you want to be able to use \fBident\fR you must not
2469 use \fB-kv\fR.
2470 .SP
2471 .SH "export options"
2472 .SP
2473 These standard options are supported by \fBexport\fR
2474 (see node `Common options\(aq in the CVS manual, for a complete description of
2475 them):
2476 .SP
2477 .IP "" 0
2478 \fB-D \fIdate\fB\fR
2479 .IP "" 2
2480 Use the most recent revision no later than \fIdate\fR.
2481 .SP
2482 .IP "" 0
2483 \fB-f\fR
2484 .IP "" 2
2485 If no matching revision is found, retrieve the most
2486 recent revision (instead of ignoring the file).
2487 .SP
2488 .IP "" 0
2489 \fB-l\fR
2490 .IP "" 2
2491 Local; run only in current working directory.
2492 .SP
2493 .IP "" 0
2494 \fB-n\fR
2495 .IP "" 2
2496 Do not run any checkout program.
2497 .SP
2498 .IP "" 0
2499 \fB-R\fR
2500 .IP "" 2
2501 Export directories recursively.  This is on by default.
2502 .SP
2503 .IP "" 0
2504 \fB-r \fItag\fB\fR
2505 .IP "" 2
2506 Use revision \fItag\fR.
2507 .SP
2508 In addition, these options (that are common to
2509 \fBcheckout\fR and \fBexport\fR) are also supported:
2510 .SP
2511 .IP "" 0
2512 \fB-d \fIdir\fB\fR
2513 .IP "" 2
2514 Create a directory called \fIdir\fR for the working
2515 files, instead of using the module name.
2516 see node `checkout options\(aq in the CVS manual, for complete details on how
2517 \fBcvs\fR handles this flag.
2518 .SP
2519 .IP "" 0
2520 \fB-k \fIsubst\fB\fR
2521 .IP "" 2
2522 Set keyword expansion mode (see node `Substitution modes\(aq in the CVS manual).
2523 .SP
2524 .IP "" 0
2525 \fB-N\fR
2526 .IP "" 2
2527 Only useful together with \fB-d \fIdir\fB\fR.
2528 see node `checkout options\(aq in the CVS manual, for complete details on how
2529 \fBcvs\fR handles this flag.
2530 .SP
2531 .SH "history"
2532 .SS "Show status of files and users"
2533 .IX "history (subcommand)"
2534 .SP
2535 .IP "\(bu" 2
2536 Synopsis:     history [-report] [-flags] [-options args] [files\&...]
2537 .IP "\(bu" 2
2538 Requires: the file \fB$CVSROOT/CVSROOT/history\fR
2539 .IP "\(bu" 2
2540 Changes: nothing.
2541 .SP
2542 \fBcvs\fR can keep a history file that tracks each use of the
2543 \fBcheckout\fR, \fBcommit\fR, \fBrtag\fR,
2544 \fBupdate\fR, and \fBrelease\fR commands.  You can
2545 use \fBhistory\fR to display this information in
2546 various formats.
2547 .SP
2548 Logging must be enabled by creating the file
2549 \fB$CVSROOT/CVSROOT/history\fR.
2550 .SP
2551 \fBNote: \fBhistory\fB uses \fB-f\fB, \fB-l\fB,
2552 \fB-n\fB, and \fB-p\fB in ways that conflict with the
2553 normal use inside \fBcvs\fB (see node `Common options\(aq in the CVS manual).\fR
2554 .SP
2555 .SH "history options"
2556 .SP
2557 Several options (shown above as \fB-report\fR)  control  what
2558 kind of report is generated:
2559 .SP
2560 .IP "" 0
2561 \fB-c\fR
2562 .IP "" 2
2563 Report on each time commit was used (i.e., each time
2564 the repository was modified).
2565 .SP
2566 .IP "" 0
2567 \fB-e\fR
2568 .IP "" 2
2569 Everything (all record types).  Equivalent to
2570 specifying \fB-x\fR with all record types.  Of course,
2571 \fB-e\fR will also include record types which are
2572 added in a future version of \fBcvs\fR; if you are
2573 writing a script which can only handle certain record
2574 types, you\(aqll want to specify \fB-x\fR.
2575 .SP
2576 .IP "" 0
2577 \fB-m \fImodule\fB\fR
2578 .IP "" 2
2579 Report on a particular module.  (You can meaningfully
2580 use \fB-m\fR more than once on the command line.)
2581 .SP
2582 .IP "" 0
2583 \fB-o\fR
2584 .IP "" 2
2585 Report on checked-out modules.  This is the default report type.
2586 .SP
2587 .IP "" 0
2588 \fB-T\fR
2589 .IP "" 2
2590 Report on all tags.
2591 .SP
2592 .IP "" 0
2593 \fB-x \fItype\fB\fR
2594 .IP "" 2
2595 Extract a particular set of record types \fItype\fR from the \fBcvs\fR
2596 history.  The types are indicated by single letters,
2597 which you may specify in combination.
2598 .SP
2599 Certain commands have a single record type:
2600 .SP
2601 .IP "" 2
2602 \fBF\fR
2603 .IP "" 4
2604 release
2605 .IP "" 2
2606 \fBO\fR
2607 .IP "" 4
2608 checkout
2609 .IP "" 2
2610 \fBE\fR
2611 .IP "" 4
2612 export
2613 .IP "" 2
2614 \fBT\fR
2615 .IP "" 4
2616 rtag
2617 .SP
2618 One of five record types may result from an update:
2619 .SP
2620 .IP "" 2
2621 \fBC\fR
2622 .IP "" 4
2623 A merge was necessary but collisions were
2624 detected (requiring manual merging).
2625 .IP "" 2
2626 \fBG\fR
2627 .IP "" 4
2628 A merge was necessary and it succeeded.
2629 .IP "" 2
2630 \fBU\fR
2631 .IP "" 4
2632 A working file was copied from the repository.
2633 .IP "" 2
2634 \fBP\fR
2635 .IP "" 4
2636 A working file was patched to match the repository.
2637 .IP "" 2
2638 \fBW\fR
2639 .IP "" 4
2640 The working copy of a file was deleted during
2641 update (because it was gone from the repository).
2642 .SP
2643 One of three record types results from commit:
2644 .SP
2645 .IP "" 2
2646 \fBA\fR
2647 .IP "" 4
2648 A file was added for the first time.
2649 .IP "" 2
2650 \fBM\fR
2651 .IP "" 4
2652 A file was modified.
2653 .IP "" 2
2654 \fBR\fR
2655 .IP "" 4
2656 A file was removed.
2657 .SP
2658 The options shown as \fB-flags\fR constrain or expand
2659 the report without requiring option arguments:
2660 .SP
2661 .IP "" 0
2662 \fB-a\fR
2663 .IP "" 2
2664 Show data for all users (the default is to show data
2665 only for the user executing \fBhistory\fR).
2666 .SP
2667 .IP "" 0
2668 \fB-l\fR
2669 .IP "" 2
2670 Show last modification only.
2671 .SP
2672 .IP "" 0
2673 \fB-w\fR
2674 .IP "" 2
2675 Show only the records for modifications done from the
2676 same working directory where \fBhistory\fR is
2677 executing.
2678 .SP
2679 The options shown as \fB-options \fIargs\fB\fR constrain the report
2680 based on an argument:
2681 .SP
2682 .IP "" 0
2683 \fB-b \fIstr\fB\fR
2684 .IP "" 2
2685 Show data back to a record containing  the  string
2686 \fIstr\fR  in  either the module name, the file name, or
2687 the repository path.
2688 .SP
2689 .IP "" 0
2690 \fB-D \fIdate\fB\fR
2691 .IP "" 2
2692 Show data since \fIdate\fR.  This is slightly different
2693 from the normal use of \fB-D \fIdate\fB\fR, which
2694 selects the newest revision older than \fIdate\fR.
2695 .SP
2696 .IP "" 0
2697 \fB-f \fIfile\fB\fR
2698 .IP "" 2
2699 Show data for a particular file
2700 (you can specify several \fB-f\fR options on the same command line).
2701 This is equivalent to specifying the file on the command line.
2702 .SP
2703 .IP "" 0
2704 \fB-n \fImodule\fB\fR
2705 .IP "" 2
2706 Show data for a particular module
2707 (you can specify several \fB-n\fR options on the same command line).
2708 .SP
2709 .IP "" 0
2710 \fB-p \fIrepository\fB\fR
2711 .IP "" 2
2712 Show data for a particular source repository  (you
2713 can specify several \fB-p\fR options on the same command
2714 line).
2715 .SP
2716 .IP "" 0
2717 \fB-r \fIrev\fB\fR
2718 .IP "" 2
2719 Show records referring to revisions since the revision
2720 or tag named \fIrev\fR appears in individual \fBrcs\fR
2721 files.  Each \fBrcs\fR file is searched for the revision or
2722 tag.
2723 .SP
2724 .IP "" 0
2725 \fB-t \fItag\fB\fR
2726 .IP "" 2
2727 Show records since tag \fItag\fR was last added to the
2728 history file.  This differs from the \fB-r\fR flag
2729 above in that it reads only the history file, not the
2730 \fBrcs\fR files, and is much faster.
2731 .SP
2732 .IP "" 0
2733 \fB-u \fIname\fB\fR
2734 .IP "" 2
2735 Show records for user \fIname\fR.
2736 .SP
2737 .IP "" 0
2738 \fB-z \fItimezone\fB\fR
2739 .IP "" 2
2740 Show times in the selected records using the specified
2741 time zone instead of UTC.
2742 .SP
2743 .SH "import"
2744 .SS "Import sources into CVS, using vendor branches"
2745 .IX "import (subcommand)"
2746 .SP
2747 .IP "\(bu" 2
2748 Synopsis: import [-options] repository vendortag releasetag\&...
2749 .IP "\(bu" 2
2750 Requires: Repository, source distribution directory.
2751 .IP "\(bu" 2
2752 Changes: repository.
2753 .SP
2754 Use \fBimport\fR to incorporate an entire source
2755 distribution from an outside source (e.g., a source
2756 vendor) into your source repository directory.  You can
2757 use this command both for initial creation of a
2758 repository, and for wholesale updates to the module
2759 from the outside source.  see node `Tracking sources\(aq in the CVS manual, for
2760 a discussion on this subject.
2761 .SP
2762 The \fIrepository\fR argument gives a directory name
2763 (or a path to a directory) under the \fBcvs\fR root directory
2764 for repositories; if the directory did not exist,
2765 import creates it.
2766 .SP
2767 When you use import for updates to source that has been
2768 modified in your source repository (since a prior
2769 import), it will notify you of any files that conflict
2770 in the two branches of development; use \fBcheckout
2771 -j\fR to reconcile the differences, as import instructs
2772 you to do.
2773 .SP
2774 If \fBcvs\fR decides a file should be ignored
2775 (see node `cvsignore\(aq in the CVS manual), it does not import it and prints
2776 \fBI \fR followed by the filename (see node `import output\(aq in the CVS manual, for a
2777 complete description of the output).
2778 .SP
2779 If the file \fB$CVSROOT/CVSROOT/cvswrappers\fR exists,
2780 any file whose names match the specifications in that
2781 file will be treated as packages and the appropriate
2782 filtering will be performed on the file/directory
2783 before being imported.  see node `Wrappers\(aq in the CVS manual.
2784 .SP
2785 The outside source is saved in a first-level
2786 branch, by default 1.1.1.  Updates are leaves of this
2787 branch; for example, files from the first imported
2788 collection of source will be revision 1.1.1.1, then
2789 files from the first imported update will be revision
2790 1.1.1.2, and so on.
2791 .SP
2792 At least three arguments are required.
2793 \fIrepository\fR is needed to identify the collection
2794 of source.  \fIvendortag\fR is a tag for the entire
2795 branch (e.g., for 1.1.1).  You must also specify at
2796 least one \fIreleasetag\fR to uniquely identify the files at
2797 the leaves created each time you execute \fBimport\fR.  The
2798 \fIreleasetag\fR should be new, not previously existing in the
2799 repository file, and uniquely identify the imported release,
2800 .SP
2801 Note that \fBimport\fR does \fInot\fR change the
2802 directory in which you invoke it.  In particular, it
2803 does not set up that directory as a \fBcvs\fR working
2804 directory; if you want to work with the sources import
2805 them first and then check them out into a different
2806 directory (see node `Getting the source\(aq in the CVS manual).
2807 .SP
2808 .SH "import options"
2809 .SP
2810 This standard option is supported by \fBimport\fR
2811 (see node `Common options\(aq in the CVS manual, for a complete description):
2812 .SP
2813 .IP "" 0
2814 \fB-m \fImessage\fB\fR
2815 .IP "" 2
2816 Use \fImessage\fR as log information, instead of
2817 invoking an editor.
2818 .SP
2819 There are the following additional special options.
2820 .SP
2821 .IP "" 0
2822 \fB-b \fIbranch\fB\fR
2823 .IP "" 2
2824 See see node `Multiple vendor branches\(aq in the CVS manual.
2825 .SP
2826 .IP "" 0
2827 \fB-k \fIsubst\fB\fR
2828 .IP "" 2
2829 Indicate the keyword expansion mode desired.  This
2830 setting will apply to all files created during the
2831 import, but not to any files that previously existed in
2832 the repository.  See see node `Substitution modes\(aq in the CVS manual, for a
2833 list of valid \fB-k\fR settings.
2834 .SP
2835 .IP "" 0
2836 \fB-I \fIname\fB\fR
2837 .IP "" 2
2838 Specify file names that should be ignored during
2839 import.  You can use this option repeatedly.  To avoid
2840 ignoring any files at all (even those ignored by
2841 default), specify \`-I !\(aq.
2842 .SP
2843 \fIname\fR can be a file name pattern of the same type
2844 that you can specify in the \fB.cvsignore\fR file.
2845 see node `cvsignore\(aq in the CVS manual.
2846 .SP
2847 .IP "" 0
2848 \fB-W \fIspec\fB\fR
2849 .IP "" 2
2850 Specify file names that should be filtered during
2851 import.  You can use this option repeatedly.
2852 .SP
2853 \fIspec\fR can be a file name pattern of the same type
2854 that you can specify in the \fB.cvswrappers\fR
2855 file. see node `Wrappers\(aq in the CVS manual.
2856 .SP
2857 .IP "" 0
2858 \fB-X\fR
2859 .IP "" 2
2860 Modify the algorithm used by \fBcvs\fR when importing new files
2861 so that new files do not immediately appear on the main trunk.
2862 .SP
2863 Specifically, this flag causes \fBcvs\fR to mark new files as
2864 if they were deleted on the main trunk, by taking the following
2865 steps for each file in addition to those normally taken on import:
2866 creating a new revision on the main trunk indicating that
2867 the new file is \fBdead\fR, resetting the new file\(aqs default branch,
2868 and placing the file in the Attic (see node `Attic\(aq in the CVS manual) directory.
2869 .SP
2870 Use of this option can be forced on a repository-wide basis
2871 by setting the \fBImportNewFilesToVendorBranchOnly\fR option in
2872 CVSROOT/config (see node `config\(aq in the CVS manual).
2873 .SP
2874 .SH "import output"
2875 .SP
2876 \fBimport\fR keeps you informed of its progress by printing a line
2877 for each file, preceded by one character indicating the status of the file:
2878 .SP
2879 .IP "" 0
2880 \fBU \fIfile\fB\fR
2881 .IP "" 2
2882 The file already exists in the repository and has not been locally
2883 modified; a new revision has been created (if necessary).
2884 .SP
2885 .IP "" 0
2886 \fBN \fIfile\fB\fR
2887 .IP "" 2
2888 The file is a new file which has been added to the repository.
2889 .SP
2890 .IP "" 0
2891 \fBC \fIfile\fB\fR
2892 .IP "" 2
2893 The file already exists in the repository but has been locally modified;
2894 you will have to merge the changes.
2895 .SP
2896 .IP "" 0
2897 \fBI \fIfile\fB\fR
2898 .IP "" 2
2899 The file is being ignored (see node `cvsignore\(aq in the CVS manual).
2900 .SP
2901 .IX "Symbolic link, importing"
2902 .IX "Link, symbolic, importing"
2903 .IP "" 0
2904 \fBL \fIfile\fB\fR
2905 .IP "" 2
2906 The file is a symbolic link; \fBcvs import\fR ignores symbolic links.
2907 People periodically suggest that this behavior should
2908 be changed, but if there is a consensus on what it
2909 should be changed to, it is not apparent.
2910 (Various options in the \fBmodules\fR file can be used
2911 to recreate symbolic links on checkout, update, etc.;
2912 see node `modules\(aq in the CVS manual.)
2913 .SP
2914 .SH "import examples"
2915 .SP
2916 See see node `Tracking sources\(aq in the CVS manual, and see node `From files\(aq in the CVS manual.
2917 .SP
2918 .SH "log"
2919 .SS "Print out log information for files"
2920 .IX "log (subcommand)"
2921 .SP
2922 .IP "\(bu" 2
2923 Synopsis: log [options] [files\&...]
2924 .IP "\(bu" 2
2925 Requires: repository, working directory.
2926 .IP "\(bu" 2
2927 Changes: nothing.
2928 .SP
2929 Display log information for files.  \fBlog\fR used to
2930 call the \fBrcs\fR utility \fBrlog\fR.  Although this
2931 is no longer true in the current sources, this history
2932 determines the format of the output and the options,
2933 which are not quite in the style of the other \fBcvs\fR
2934 commands.
2935 .SP
2936 .IX "Timezone, in output"
2937 .IX "Zone, time, in output"
2938 The output includes the location of the \fBrcs\fR file,
2939 the \fIhead\fR revision (the latest revision on the
2940 trunk), all symbolic names (tags) and some other
2941 things.  For each revision, the revision number, the
2942 date, the
2943 author, the number of lines added/deleted and the log
2944 message are printed.  All dates are displayed in local
2945 time at the client.  This is typically specified in the
2946 \fB$TZ\fR environment variable, which can be set to
2947 govern how \fBlog\fR displays dates.
2948 .SP
2949 \fBNote: \fBlog\fB uses \fB-R\fB in a way that conflicts
2950 with the normal use inside \fBcvs\fB (see node `Common options\(aq in the CVS manual).\fR
2951 .SP
2952 .SH "log options"
2953 .SP
2954 By default, \fBlog\fR prints all information that is
2955 available.  All other options restrict the output.
2956 .SP
2957 .IP "" 0
2958 \fB-b\fR
2959 .IP "" 2
2960 Print information about the revisions on the default
2961 branch, normally the highest branch on the trunk.
2962 .SP
2963 .IP "" 0
2964 \fB-d \fIdates\fB\fR
2965 .IP "" 2
2966 Print information about revisions with a checkin
2967 date/time in the range given by the
2968 semicolon-separated list of dates.  The date formats
2969 accepted are those accepted by the \fB-D\fR option to
2970 many other \fBcvs\fR commands (see node `Common options\(aq in the CVS manual).
2971 Dates can be combined into ranges as follows:
2972 .SP
2973 .IP "" 2
2974 \fB\fId1\fB<\fId2\fB\fR
2975 .IP "" 4
2976 .IP "" 2
2977 \fB\fId2\fB>\fId1\fB\fR
2978 .IP "" 4
2979 Select the revisions that were deposited between
2980 \fId1\fR and \fId2\fR.
2981 .SP
2982 .IP "" 2
2983 \fB<\fId\fB\fR
2984 .IP "" 4
2985 .IP "" 2
2986 \fB\fId\fB>\fR
2987 .IP "" 4
2988 Select all revisions dated \fId\fR or earlier.
2989 .SP
2990 .IP "" 2
2991 \fB\fId\fB<\fR
2992 .IP "" 4
2993 .IP "" 2
2994 \fB>\fId\fB\fR
2995 .IP "" 4
2996 Select all revisions dated \fId\fR or later.
2997 .SP
2998 .IP "" 2
2999 \fB\fId\fB\fR
3000 .IP "" 4
3001 Select the single, latest revision dated \fId\fR or
3002 earlier.
3003 .SP
3004 The \fB>\fR or \fB<\fR characters may be followed by
3005 \fB=\fR to indicate an inclusive range rather than an
3006 exclusive one.
3007 .SP
3008 Note that the separator is a semicolon (;).
3009 .SP
3010 .IP "" 0
3011 \fB-h\fR
3012 .IP "" 2
3013 Print only the name of the \fBrcs\fR file, name
3014 of the file in the working directory, head,
3015 default branch, access list, locks, symbolic names, and
3016 suffix.
3017 .SP
3018 .IP "" 0
3019 \fB-l\fR
3020 .IP "" 2
3021 Local; run only in current working directory.  (Default
3022 is to run recursively).
3023 .SP
3024 .IP "" 0
3025 \fB-N\fR
3026 .IP "" 2
3027 Do not print the list of tags for this file.  This
3028 option can be very useful when your site uses a lot of
3029 tags, so rather than "more"\(aqing over 3 pages of tag
3030 information, the log information is presented without
3031 tags at all.
3032 .SP
3033 .IP "" 0
3034 \fB-R\fR
3035 .IP "" 2
3036 Print only the name of the \fBrcs\fR file.
3037 .SP
3038 .IP "" 0
3039 \fB-r\fIrevisions\fB\fR
3040 .IP "" 2
3041 Print information about revisions given in the
3042 comma-separated list \fIrevisions\fR of revisions and
3043 ranges.  The following table explains the available
3044 range formats:
3045 .SP
3046 .IP "" 2
3047 \fB\fIrev1\fB:\fIrev2\fB\fR
3048 .IP "" 4
3049 Revisions \fIrev1\fR to \fIrev2\fR (which must be on
3050 the same branch).
3051 .SP
3052 .IP "" 2
3053 \fB\fIrev1\fB::\fIrev2\fB\fR
3054 .IP "" 4
3055 The same, but excluding \fIrev1\fR.
3056 .SP
3057 .IP "" 2
3058 \fB:\fIrev\fB\fR
3059 .IP "" 4
3060 .IP "" 2
3061 \fB::\fIrev\fB\fR
3062 .IP "" 4
3063 Revisions from the beginning of the branch up to
3064 and including \fIrev\fR.
3065 .SP
3066 .IP "" 2
3067 \fB\fIrev\fB:\fR
3068 .IP "" 4
3069 Revisions starting with \fIrev\fR to the end of the
3070 branch containing \fIrev\fR.
3071 .SP
3072 .IP "" 2
3073 \fB\fIrev\fB::\fR
3074 .IP "" 4
3075 Revisions starting just after \fIrev\fR to the end of the
3076 branch containing \fIrev\fR.
3077 .SP
3078 .IP "" 2
3079 \fB\fIbranch\fB\fR
3080 .IP "" 4
3081 An argument that is a branch means all revisions on
3082 that branch.
3083 .SP
3084 .IP "" 2
3085 \fB\fIbranch1\fB:\fIbranch2\fB\fR
3086 .IP "" 4
3087 .IP "" 2
3088 \fB\fIbranch1\fB::\fIbranch2\fB\fR
3089 .IP "" 4
3090 A range of branches means all revisions
3091 on the branches in that range.
3092 .SP
3093 .IP "" 2
3094 \fB\fIbranch\fB.\fR
3095 .IP "" 4
3096 The latest revision in \fIbranch\fR.
3097 .SP
3098 A bare \fB-r\fR with no revisions means the latest
3099 revision on the default branch, normally the trunk.
3100 There can be no space between the \fB-r\fR option and
3101 its argument.
3102 .SP
3103 .IP "" 0
3104 \fB-S\fR
3105 .IP "" 2
3106 Suppress the header if no revisions are selected.
3107 .SP
3108 .IP "" 0
3109 \fB-s \fIstates\fB\fR
3110 .IP "" 2
3111 Print information about revisions whose state
3112 attributes match one of the states given in the
3113 comma-separated list \fIstates\fR.
3114 .SP
3115 .IP "" 0
3116 \fB-t\fR
3117 .IP "" 2
3118 Print the same as \fB-h\fR, plus the descriptive text.
3119 .SP
3120 .IP "" 0
3121 \fB-w\fIlogins\fB\fR
3122 .IP "" 2
3123 Print information about revisions checked in by users
3124 with login names appearing in the comma-separated list
3125 \fIlogins\fR.  If \fIlogins\fR is omitted, the user\(aqs
3126 login is assumed.  There can be no space between the
3127 \fB-w\fR option and its argument.
3128 .SP
3129 \fBlog\fR prints the intersection of the revisions
3130 selected with the options \fB-d\fR, \fB-s\fR, and
3131 \fB-w\fR, intersected with the union of the revisions
3132 selected by \fB-b\fR and \fB-r\fR.
3133 .SP
3134 .SH "log examples"
3135 .SP
3136 .IX "Timezone, in output"
3137 .IX "Zone, time, in output"
3138 Since \fBlog\fR shows dates in local time,
3139 you might want to see them in Coordinated Universal Time (UTC) or
3140 some other timezone.
3141 To do this you can set your \fB$TZ\fR environment
3142 variable before invoking \fBcvs\fR:
3143 .SP
3144 .PD 0
3145 .SP
3146 .IP "" 2
3147 $ TZ=UTC cvs log foo.c
3148 .IP "" 2
3149 $ TZ=EST cvs log bar.c
3150
3151 .PD
3152 .IP "" 0
3153 .SP
3154 (If you are using a \fBcsh\fR-style shell, like \fBtcsh\fR,
3155 you would need to prefix the examples above with \fBenv\fR.)
3156 .SP
3157 .SH "ls & rls"
3158 .IX "ls (subcommand)"
3159 .IX "rls (subcommand)"
3160 .SP
3161 .IP "\(bu" 2
3162 ls [-e | -l] [-RP] [-r revision] [-D date] [path\&...]
3163 .IP "\(bu" 2
3164 Requires: repository for \fBrls\fR, repository & working directory for
3165 \fBls\fR.
3166 .IP "\(bu" 2
3167 Changes: nothing.
3168 .IP "\(bu" 2
3169 Synonym: \fBdir\fR & \fBlist\fR are synonyms for \fBls\fR and \fBrdir\fR
3170 & \fBrlist\fR are synonyms for \fBrls\fR.
3171 .SP
3172 The \fBls\fR and \fBrls\fR commands are used to list
3173 files and directories in the repository.
3174 .SP
3175 By default \fBls\fR lists the files and directories
3176 that belong in your working directory, what would be
3177 there after an \fBupdate\fR.
3178 .SP
3179 By default \fBrls\fR lists the files and directories
3180 on the tip of the trunk in the topmost directory of the
3181 repository.
3182 .SP
3183 Both commands accept an optional list of file and
3184 directory names, relative to the working directory for
3185 \fBls\fR and the topmost directory of the repository
3186 for \fBrls\fR.  Neither is recursive by default.
3187 .SP
3188 .SH "ls & rls options"
3189 .SP
3190 These standard options are supported by \fBls\fR & \fBrls\fR:
3191 .SP
3192 .IP "" 0
3193 \fB-d\fR
3194 .IP "" 2
3195 Show dead revisions (with tag when specified).
3196 .SP
3197 .IP "" 0
3198 \fB-e\fR
3199 .IP "" 2
3200 Display in CVS/Entries format.  This format is meant to remain easily parsable
3201 by automation.
3202 .SP
3203 .IP "" 0
3204 \fB-l\fR
3205 .IP "" 2
3206 Display all details.
3207 .SP
3208 .IP "" 0
3209 \fB-P\fR
3210 .IP "" 2
3211 Don\(aqt list contents of empty directories when recursing.
3212 .SP
3213 .IP "" 0
3214 \fB-R\fR
3215 .IP "" 2
3216 List recursively.
3217 .SP
3218 .IP "" 0
3219 \fB-r \fIrevision\fB\fR
3220 .IP "" 2
3221 Show files with revision or tag.
3222 .SP
3223 .IP "" 0
3224 \fB-D \fIdate\fB\fR
3225 .IP "" 2
3226 Show files from date.
3227 .SP
3228 .SH "rls examples"
3229 .SP
3230 .PD 0
3231 .SP
3232 .IP "" 2
3233 $ cvs rls
3234 .IP "" 2
3235 cvs rls: Listing module: \`.\(aq
3236 .IP "" 2
3237 CVSROOT
3238 .IP "" 2
3239 first-dir
3240
3241 .PD
3242 .IP "" 0
3243 .SP
3244 .PD 0
3245 .SP
3246 .IP "" 2
3247 $ cvs rls CVSROOT
3248 .IP "" 2
3249 cvs rls: Listing module: \`CVSROOT\(aq
3250 .IP "" 2
3251 checkoutlist
3252 .IP "" 2
3253 commitinfo
3254 .IP "" 2
3255 config
3256 .IP "" 2
3257 cvswrappers
3258 .IP "" 2
3259 loginfo
3260 .IP "" 2
3261 modules
3262 .IP "" 2
3263 notify
3264 .IP "" 2
3265 rcsinfo
3266 .IP "" 2
3267 taginfo
3268 .IP "" 2
3269 verifymsg
3270 .SP
3271
3272 .PD
3273 .IP "" 0
3274 .SP
3275 .SH "rdiff"
3276 .SS "\(aqpatch\(aq format diffs between releases"
3277 .IX "rdiff (subcommand)"
3278 .SP
3279 .IP "\(bu" 2
3280 rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules\&...
3281 .IP "\(bu" 2
3282 Requires: repository.
3283 .IP "\(bu" 2
3284 Changes: nothing.
3285 .IP "\(bu" 2
3286 Synonym: patch
3287 .SP
3288 Builds a Larry Wall format patch(1) file between two
3289 releases, that can be fed directly into the \fBpatch\fR
3290 program to bring an old release up-to-date with the new
3291 release.  (This is one of the few \fBcvs\fR commands that
3292 operates directly from the repository, and doesn\(aqt
3293 require a prior checkout.) The diff output is sent to
3294 the standard output device.
3295 .SP
3296 You can specify (using the standard \fB-r\fR and
3297 \fB-D\fR options) any combination of one or two
3298 revisions or dates.  If only one revision or date is
3299 specified, the patch file reflects differences between
3300 that revision or date and the current head revisions in
3301 the \fBrcs\fR file.
3302 .SP
3303 Note that if the software release affected is contained
3304 in more than one directory, then it may be necessary to
3305 specify the \fB-p\fR option to the \fBpatch\fR command when
3306 patching the old sources, so that \fBpatch\fR is able to find
3307 the files that are located in other directories.
3308 .SP
3309 .SH "rdiff options"
3310 .SP
3311 These standard options are supported by \fBrdiff\fR
3312 (see node `Common options\(aq in the CVS manual, for a complete description of
3313 them):
3314 .SP
3315 .IP "" 0
3316 \fB-D \fIdate\fB\fR
3317 .IP "" 2
3318 Use the most recent revision no later than \fIdate\fR.
3319 .SP
3320 .IP "" 0
3321 \fB-f\fR
3322 .IP "" 2
3323 If no matching revision is found, retrieve the most
3324 recent revision (instead of ignoring the file).
3325 .SP
3326 .IP "" 0
3327 \fB-l\fR
3328 .IP "" 2
3329 Local; don\(aqt descend subdirectories.
3330 .SP
3331 .IP "" 0
3332 \fB-R\fR
3333 .IP "" 2
3334 Examine directories recursively.  This option is on by default.
3335 .SP
3336 .IP "" 0
3337 \fB-r \fItag\fB\fR
3338 .IP "" 2
3339 Use revision \fItag\fR.
3340 .SP
3341 In addition to the above, these options are available:
3342 .SP
3343 .IP "" 0
3344 \fB-c\fR
3345 .IP "" 2
3346 Use the context diff format.  This is the default format.
3347 .SP
3348 .IP "" 0
3349 \fB-s\fR
3350 .IP "" 2
3351 Create a summary change report instead of a patch.  The
3352 summary includes information about files that were
3353 changed or added between the releases.  It is sent to
3354 the standard output device.  This is useful for finding
3355 out, for example, which files have changed between two
3356 dates or revisions.
3357 .SP
3358 .IP "" 0
3359 \fB-t\fR
3360 .IP "" 2
3361 A diff of the top two revisions is sent to the standard
3362 output device.  This is most useful for seeing what the
3363 last change to a file was.
3364 .SP
3365 .IP "" 0
3366 \fB-u\fR
3367 .IP "" 2
3368 Use the unidiff format for the context diffs.
3369 Remember that old versions
3370 of the \fBpatch\fR program can\(aqt handle the unidiff
3371 format, so if you plan to post this patch to the net
3372 you should probably not use \fB-u\fR.
3373 .SP
3374 .IP "" 0
3375 \fB-V \fIvn\fB\fR
3376 .IP "" 2
3377 Expand keywords according to the rules current in
3378 \fBrcs\fR version \fIvn\fR (the expansion format changed with
3379 \fBrcs\fR version 5).  Note that this option is no
3380 longer accepted.  \fBcvs\fR will always expand keywords the
3381 way that \fBrcs\fR version 5 does.
3382 .SP
3383 .SH "rdiff examples"
3384 .SP
3385 Suppose you receive mail from \fRfoo@example.net\fR asking for an
3386 update from release 1.2 to 1.4 of the tc compiler.  You
3387 have no such patches on hand, but with \fBcvs\fR that can
3388 easily be fixed with a command such as this:
3389 .SP
3390 .PD 0
3391 .SP
3392 .IP "" 2
3393 $ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \\
3394 .IP "" 2
3395 $$ Mail -s \(aqThe patches you asked for\(aq foo@example.net
3396
3397 .PD
3398 .IP "" 0
3399 .SP
3400 Suppose you have made release 1.3, and forked a branch
3401 called \fBR_1_3fix\fR for bug fixes.  \fBR_1_3_1\fR
3402 corresponds to release 1.3.1, which was made some time
3403 ago.  Now, you want to see how much development has been
3404 done on the branch.  This command can be used:
3405 .SP
3406 .PD 0
3407 .SP
3408 .IP "" 2
3409 $ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
3410 .IP "" 2
3411 cvs rdiff: Diffing module-name
3412 .IP "" 2
3413 File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
3414 .IP "" 2
3415 File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
3416 .IP "" 2
3417 File bar.h,v changed from revision 1.29.2.1 to 1.2
3418
3419 .PD
3420 .IP "" 0
3421 .SP
3422 .SH "release"
3423 .SS "Indicate that a Module is no longer in use"
3424 .IX "release (subcommand)"
3425 .SP
3426 .IP "\(bu" 2
3427 release [-d] directories\&...
3428 .IP "\(bu" 2
3429 Requires: Working directory.
3430 .IP "\(bu" 2
3431 Changes: Working directory, history log.
3432 .SP
3433 This command is meant to safely cancel the effect of
3434 \fBcvs checkout\fR.  Since \fBcvs\fR doesn\(aqt lock files, it
3435 isn\(aqt strictly necessary to use this command.  You can
3436 always simply delete your working directory, if you
3437 like; but you risk losing changes you may have
3438 forgotten, and you leave no trace in the \fBcvs\fR history
3439 file (see node `history file\(aq in the CVS manual) that you\(aqve abandoned your
3440 checkout.
3441 .SP
3442 Use \fBcvs release\fR to avoid these problems.  This
3443 command checks that no uncommitted changes are
3444 present; that you are executing it from immediately
3445 above a \fBcvs\fR working directory; and that the repository
3446 recorded for your files is the same as the repository
3447 defined in the module database.
3448 .SP
3449 If all these conditions are true, \fBcvs release\fR
3450 leaves a record of its execution (attesting to your
3451 intentionally abandoning your checkout) in the \fBcvs\fR
3452 history log.
3453 .SP
3454 .SH "release options"
3455 .SP
3456 The \fBrelease\fR command supports one command option:
3457 .SP
3458 .IP "" 0
3459 \fB-d\fR
3460 .IP "" 2
3461 Delete your working copy of the file if the release
3462 succeeds.  If this flag is not given your files will
3463 remain in your working directory.
3464 .SP
3465 \fBWARNING:  The \fBrelease\fB command deletes
3466 all directories and files recursively.  This
3467 has the very serious side-effect that any directory
3468 that you have created inside your checked-out sources,
3469 and not added to the repository (using the \fBadd\fB
3470 command; see node `Adding files\(aq in the CVS manual) will be silently deleted\(emeven
3471 if it is non-empty!\fR
3472 .SP
3473 .SH "release output"
3474 .SP
3475 Before \fBrelease\fR releases your sources it will
3476 print a one-line message for any file that is not
3477 up-to-date.
3478 .SP
3479 .IP "" 0
3480 \fBU \fIfile\fB\fR
3481 .IP "" 2
3482 .IP "" 0
3483 \fBP \fIfile\fB\fR
3484 .IP "" 2
3485 There exists a newer revision of this file in the
3486 repository, and you have not modified your local copy
3487 of the file (\fBU\fR and \fBP\fR mean the same thing).
3488 .SP
3489 .IP "" 0
3490 \fBA \fIfile\fB\fR
3491 .IP "" 2
3492 The file has been added to your private copy of the
3493 sources, but has not yet been committed to the
3494 repository.  If you delete your copy of the sources
3495 this file will be lost.
3496 .SP
3497 .IP "" 0
3498 \fBR \fIfile\fB\fR
3499 .IP "" 2
3500 The file has been removed from your private copy of the
3501 sources, but has not yet been removed from the
3502 repository, since you have not yet committed the
3503 removal.  see node `commit\(aq in the CVS manual.
3504 .SP
3505 .IP "" 0
3506 \fBM \fIfile\fB\fR
3507 .IP "" 2
3508 The file is modified in your working directory.  There
3509 might also be a newer revision inside the repository.
3510 .SP
3511 .IP "" 0
3512 \fB? \fIfile\fB\fR
3513 .IP "" 2
3514 \fIfile\fR is in your working directory, but does not
3515 correspond to anything in the source repository, and is
3516 not in the list of files for \fBcvs\fR to ignore (see the
3517 description of the \fB-I\fR option, and
3518 see node `cvsignore\(aq in the CVS manual).  If you remove your working
3519 sources, this file will be lost.
3520 .SP
3521 .SH "release examples"
3522 .SP
3523 Release the \fBtc\fR directory, and delete your local working copy
3524 of the files.
3525 .SP
3526 .PD 0
3527 .SP
3528 .IP "" 2
3529 $ cd \&..         # \fRYou must stand immediately above the\fR
3530 .IP "" 2
3531                 # \fRsources when you issue \fBcvs release\fR.\fR
3532 .IP "" 2
3533 $ cvs release -d tc
3534 .IP "" 2
3535 You have [0] altered files in this repository.
3536 .IP "" 2
3537 Are you sure you want to release (and delete) directory \`tc\(aq: y
3538 .IP "" 2
3539 $
3540
3541 .PD
3542 .IP "" 0
3543 .SP
3544 .SH "update"
3545 .SS "Bring work tree in sync with repository"
3546 .IX "update (subcommand)"
3547 .SP
3548 .IP "\(bu" 2
3549 update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W spec] files\&...
3550 .IP "\(bu" 2
3551 Requires: repository, working directory.
3552 .IP "\(bu" 2
3553 Changes: working directory.
3554 .SP
3555 After you\(aqve run checkout to create your private copy
3556 of source from the common repository, other developers
3557 will continue changing the central source.  From time
3558 to time, when it is convenient in your development
3559 process, you can use the \fBupdate\fR command from
3560 within your working directory to reconcile your work
3561 with any revisions applied to the source repository
3562 since your last checkout or update.  Without the \fB-C\fR
3563 option, \fBupdate\fR will also merge any differences
3564 between the local copy of files and their base revisions
3565 into any destination revisions specified with \fB-r\fR,
3566 \fB-D\fR, or \fB-A\fR.
3567 .SP
3568 .SH "update options"
3569 .SP
3570 These standard options are available with \fBupdate\fR
3571 (see node `Common options\(aq in the CVS manual, for a complete description of
3572 them):
3573 .SP
3574 .IP "" 0
3575 \fB-D date\fR
3576 .IP "" 2
3577 Use the most recent revision no later than \fIdate\fR.
3578 This option is sticky, and implies \fB-P\fR.
3579 See see node `Sticky tags\(aq in the CVS manual, for more information on sticky tags/dates.
3580 .SP
3581 .IP "" 0
3582 \fB-f\fR
3583 .IP "" 2
3584 Only useful with the \fB-D \fIdate\fB\fR or \fB-r
3585 \fItag\fB\fR flags.  If no matching revision is found,
3586 retrieve the most recent revision (instead of ignoring
3587 the file).
3588 .SP
3589 .IP "" 0
3590 \fB-k \fIkflag\fB\fR
3591 .IP "" 2
3592 Process keywords according to \fIkflag\fR.  See
3593 see node `Keyword substitution\(aq in the CVS manual.
3594 This option is sticky; future updates of
3595 this file in this working directory will use the same
3596 \fIkflag\fR.  The \fBstatus\fR command can be viewed
3597 to see the sticky options.  See see node `Invoking CVS\(aq in the CVS manual, for
3598 more information on the \fBstatus\fR command.
3599 .SP
3600 .IP "" 0
3601 \fB-l\fR
3602 .IP "" 2
3603 Local; run only in current working directory.  see node `Recursive behavior\(aq in the CVS manual.
3604 .SP
3605 .IP "" 0
3606 \fB-P\fR
3607 .IP "" 2
3608 Prune empty directories.  See see node `Moving directories\(aq in the CVS manual.
3609 .SP
3610 .IP "" 0
3611 \fB-p\fR
3612 .IP "" 2
3613 Pipe files to the standard output.
3614 .SP
3615 .IP "" 0
3616 \fB-R\fR
3617 .IP "" 2
3618 Update directories recursively (default).  see node `Recursive
3619 behavior\(aq in the CVS manual.
3620 .SP
3621 .IP "" 0
3622 \fB-r rev\fR
3623 .IP "" 2
3624 Retrieve revision/tag \fIrev\fR.  This option is sticky,
3625 and implies \fB-P\fR.
3626 See see node `Sticky tags\(aq in the CVS manual, for more information on sticky tags/dates.
3627 .SP
3628 These special options are also available with
3629 \fBupdate\fR.
3630 .SP
3631 .IP "" 0
3632 \fB-A\fR
3633 .IP "" 2
3634 Reset any sticky tags, dates, or \fB-k\fR options.
3635 See see node `Sticky tags\(aq in the CVS manual, for more information on sticky tags/dates.
3636 .SP
3637 .IP "" 0
3638 \fB-C\fR
3639 .IP "" 2
3640 Overwrite locally modified files with clean copies from
3641 the repository (the modified file is saved in
3642 \fB.#\fIfile\fB.\fIrevision\fB\fR, however).
3643 .SP
3644 .IP "" 0
3645 \fB-d\fR
3646 .IP "" 2
3647 Create any directories that exist in the repository if
3648 they\(aqre missing from the working directory.  Normally,
3649 \fBupdate\fR acts only on directories and files that
3650 were already enrolled in your working directory.
3651 .SP
3652 This is useful for updating directories that were
3653 created in the repository since the initial checkout;
3654 but it has an unfortunate side effect.  If you
3655 deliberately avoided certain directories in the
3656 repository when you created your working directory
3657 (either through use of a module name or by listing
3658 explicitly the files and directories you wanted on the
3659 command line), then updating with \fB-d\fR will create
3660 those directories, which may not be what you want.
3661 .SP
3662 .IP "" 0
3663 \fB-I \fIname\fB\fR
3664 .IP "" 2
3665 Ignore files whose names match \fIname\fR (in your
3666 working directory) during the update.  You can specify
3667 \fB-I\fR more than once on the command line to specify
3668 several files to ignore.  Use \fB-I !\fR to avoid
3669 ignoring any files at all.  see node `cvsignore\(aq in the CVS manual, for other
3670 ways to make \fBcvs\fR ignore some files.
3671 .SP
3672 .IP "" 0
3673 \fB-W\fIspec\fB\fR
3674 .IP "" 2
3675 Specify file names that should be filtered during
3676 update.  You can use this option repeatedly.
3677 .SP
3678 \fIspec\fR can be a file name pattern of the same type
3679 that you can specify in the \fB.cvswrappers\fR
3680 file. see node `Wrappers\(aq in the CVS manual.
3681 .SP
3682 .IP "" 0
3683 \fB-j\fIrevision\fB\fR
3684 .IP "" 2
3685 With two \fB-j\fR options, merge changes from the
3686 revision specified with the first \fB-j\fR option to
3687 the revision specified with the second \fBj\fR option,
3688 into the working directory.
3689 .SP
3690 With one \fB-j\fR option, merge changes from the
3691 ancestor revision to the revision specified with the
3692 \fB-j\fR option, into the working directory.  The
3693 ancestor revision is the common ancestor of the
3694 revision which the working directory is based on, and
3695 the revision specified in the \fB-j\fR option.
3696 .SP
3697 Note that using a single \fB-j \fItagname\fB\fR option rather than
3698 \fB-j \fIbranchname\fB\fR to merge changes from a branch will
3699 often not remove files which were removed on the branch.
3700 see node `Merging adds and removals\(aq in the CVS manual, for more.
3701 .SP
3702 In addition, each \fB-j\fR option can contain an optional
3703 date specification which, when used with branches, can
3704 limit the chosen revision to one within a specific
3705 date.  An optional date is specified by adding a colon
3706 (:) to the tag:
3707 \fB-j\fISymbolic_Tag\fB:\fIDate_Specifier\fB\fR.
3708 .SP
3709 see node `Branching and merging\(aq in the CVS manual.
3710 .SP
3711 .SP
3712 .SH "update output"
3713 .SP
3714 \fBupdate\fR and \fBcheckout\fR keep you informed of
3715 their progress by printing a line for each file, preceded
3716 by one character indicating the status of the file:
3717 .SP
3718 .IP "" 0
3719 \fBU \fIfile\fB\fR
3720 .IP "" 2
3721 The file was brought up to date with respect to the
3722 repository.  This is done for any file that exists in
3723 the repository but not in your source, and for files
3724 that you haven\(aqt changed but are not the most recent
3725 versions available in the repository.
3726 .SP
3727 .IP "" 0
3728 \fBP \fIfile\fB\fR
3729 .IP "" 2
3730 Like \fBU\fR, but the \fBcvs\fR server sends a patch instead of an entire
3731 file.  This accomplishes the same thing as \fBU\fR using less bandwidth.
3732 .SP
3733 .IP "" 0
3734 \fBA \fIfile\fB\fR
3735 .IP "" 2
3736 The file has been added to your private copy of the
3737 sources, and will be added to the source repository
3738 when you run \fBcommit\fR on the file.  This is a
3739 reminder to you that the file needs to be committed.
3740 .SP
3741 .IP "" 0
3742 \fBR \fIfile\fB\fR
3743 .IP "" 2
3744 The file has been removed from your private copy of the
3745 sources, and will be removed from the source repository
3746 when you run \fBcommit\fR on the file.  This is a
3747 reminder to you that the file needs to be committed.
3748 .SP
3749 .IP "" 0
3750 \fBM \fIfile\fB\fR
3751 .IP "" 2
3752 The file is modified in  your  working  directory.
3753 .SP
3754 \fBM\fR can indicate one of two states for a file
3755 you\(aqre working on: either there were no modifications
3756 to the same file in the repository, so that your file
3757 remains as you last saw it; or there were modifications
3758 in the repository as well as in your copy, but they
3759 were merged successfully, without conflict, in your
3760 working directory.
3761 .SP
3762 \fBcvs\fR will print some messages if it merges your work,
3763 and a backup copy of your working file (as it looked
3764 before you ran \fBupdate\fR) will be made.  The exact
3765 name of that file is printed while \fBupdate\fR runs.
3766 .SP
3767 .IP "" 0
3768 \fBC \fIfile\fB\fR
3769 .IP "" 2
3770 .IX "\&.# files"
3771 .IX "__ files (VMS)"
3772 A conflict was detected while trying to merge your
3773 changes to \fIfile\fR with changes from the source
3774 repository.  \fIfile\fR (the copy in your working
3775 directory) is now the result of attempting to merge
3776 the two revisions; an unmodified copy of your file
3777 is also in your working directory, with the name
3778 \fB.#\fIfile\fB.\fIrevision\fB\fR where \fIrevision\fR
3779 is the revision that your modified file started
3780 from.  Resolve the conflict as described in
3781 see node `Conflicts example\(aq in the CVS manual.
3782 (Note that some systems automatically purge
3783 files that begin with \fB.#\fR if they have not been
3784 accessed for a few days.  If you intend to keep a copy
3785 of your original file, it is a very good idea to rename
3786 it.)  Under \fBvms\fR, the file name starts with
3787 \fB__\fR rather than \fB.#\fR.
3788 .SP
3789 .IP "" 0
3790 \fB? \fIfile\fB\fR
3791 .IP "" 2
3792 \fIfile\fR is in your working directory, but does not
3793 correspond to anything in the source repository, and is
3794 not in the list of files for \fBcvs\fR to ignore (see the
3795 description of the \fB-I\fR option, and
3796 see node `cvsignore\(aq in the CVS manual).
3797 .SH "AUTHORS"
3798 .TP
3799 Dick Grune
3800 Original author of the
3801 .B cvs
3802 shell script version posted to
3803 .B comp.sources.unix
3804 in the volume6 release of December, 1986.
3805 Credited with much of the
3806 .B cvs
3807 conflict resolution algorithms.
3808 .TP
3809 Brian Berliner
3810 Coder and designer of the
3811 .B cvs
3812 program itself in April, 1989, based on the original work done by Dick.
3813 .TP
3814 Jeff Polk
3815 Helped Brian with the design of the
3816 .B cvs
3817 module and vendor branch support and author of the
3818 .BR checkin ( 1 )
3819 shell script (the ancestor of \fBcvs import\fP).
3820 .TP
3821 Larry Jones, Derek R. Price, and Mark D. Baushke
3822 Have helped maintain
3823 .B cvs
3824 for many years.
3825 .TP
3826 And many others too numerous to mention here.
3827 .SH "SEE ALSO"
3828 The most comprehensive manual for CVS is
3829 Version Management with CVS by Per Cederqvist et al.  Depending on
3830 your system, you may be able to get it with the
3831 .B info CVS
3832 command or it may be available as cvs.pdf (Portable Document Format),
3833 cvs.ps (PostScript), cvs.texinfo (Texinfo source), or cvs.html.
3834 .SP
3835 For CVS updates, more information on documentation, software related
3836 to CVS, development of CVS, and more, see:
3837 .in +1i
3838 .SP
3839 .PD 0
3840 .IP "" 4
3841 .B http://cvshome.org
3842 .in -1i
3843 .SP
3844 .BR ci ( 1 ),
3845 .BR co ( 1 ),
3846 .BR cvs ( 5 ),
3847 .BR cvsbug ( 8 ),
3848 .BR diff ( 1 ),
3849 .BR grep ( 1 ),
3850 .BR patch ( 1 ),
3851 .BR rcs ( 1 ),
3852 .BR rcsdiff ( 1 ),
3853 .BR rcsmerge ( 1 ),
3854 .BR rlog ( 1 ).