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