PageRenderTime 43ms CodeModel.GetById 19ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/cvs/doc/cvs.1

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 3968 lines | 3937 code | 31 blank | 0 comment | 0 complexity | 67448ebcc103d7fe3cc0c5d37422628d MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   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"
  37cvs \- 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"
  54This manpage is a summary of some of the features of
  55\fBcvs\fP.  It is auto-generated from an appendix of the CVS manual.
  56For more in-depth documentation, please consult the
  57Cederqvist manual (via the
  58.B info CVS
  59command or otherwise,
  60as described in the SEE ALSO section of this manpage).  Cross-references
  61in this man page refer to nodes in the same.
  62.SH "CVS commands"
  63.SS "Guide to CVS commands"
  64.SP
  65This appendix describes the overall structure of
  66\fBcvs\fR commands, and describes some commands in
  67detail (others are described elsewhere; for a quick
  68reference 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
  77The overall format of all \fBcvs\fR commands is:
  78.SP
  79.PD 0
  80.SP
  81.IP "" 2
  82cvs [ 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
  90The name of the \fBcvs\fR program.
  91.SP
  92.IP "" 0
  93\fBcvs_options\fR
  94.IP "" 2
  95Some options that affect all sub-commands of \fBcvs\fR.  These are
  96described below.
  97.SP
  98.IP "" 0
  99\fBcvs_command\fR
 100.IP "" 2
 101One of several different sub-commands.  Some of the commands have
 102aliases that can be used instead; those aliases are noted in the
 103reference manual for that command.  There are only two situations
 104where you may omit \fBcvs_command\fR: \fBcvs -H\fR elicits a
 105list of available commands, and \fBcvs -v\fR displays version
 106information on \fBcvs\fR itself.
 107.SP
 108.IP "" 0
 109\fBcommand_options\fR
 110.IP "" 2
 111Options that are specific for the command.
 112.SP
 113.IP "" 0
 114\fBcommand_args\fR
 115.IP "" 2
 116Arguments to the commands.
 117.SP
 118There is unfortunately some confusion between
 119\fBcvs_options\fR and \fBcommand_options\fR.
 120When given as a \fBcvs_option\fR, some options only
 121affect some of the commands.  When given as a
 122\fBcommand_option\fR it may have a different meaning, and
 123be accepted by more commands.  In other words, do not
 124take the above categorization too seriously.  Look at
 125the 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
 132succeeded or failed by setting its \fIexit status\fR.
 133The exact way of testing the exit status will vary from
 134one operating system to another.  For example in a unix
 135shell script the \fB$?\fR variable will be 0 if the
 136last command returned a successful exit status, or
 137greater than 0 if the exit status indicated failure.
 138.SP
 139If \fBcvs\fR is successful, it returns a successful status;
 140if there is an error, it prints an error message and
 141returns a failure status.  The one exception to this is
 142the \fBcvs diff\fR command.  It will return a
 143successful status if it found no differences, or a
 144failure status if there were differences or if there
 145was an error.  Because this behavior provides no good
 146way to detect errors, in the future it is possible that
 147\fBcvs diff\fR will be changed to behave like the
 148other \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
 155There are some \fBcommand_options\fR that are used so
 156often that you might have set up an alias or some other
 157means to make sure you always specify that option.  One
 158example (the one that drove the implementation of the
 159\fB.cvsrc\fR support, actually) is that many people find the
 160default output of the \fBdiff\fR command to be very
 161hard to read, and that either context diffs or unidiffs
 162are much easier to understand.
 163.SP
 164The \fB~/.cvsrc\fR file is a way that you can add
 165default options to \fBcvs_commands\fR within cvs,
 166instead of relying on aliases or other shell scripts.
 167.SP
 168The format of the \fB~/.cvsrc\fR file is simple.  The
 169file is searched for a line that begins with the same
 170name as the \fBcvs_command\fR being executed.  If a
 171match is found, then the remainder of the line is split
 172up (at whitespace characters) into separate options and
 173added to the command arguments \fIbefore\fR any
 174options from the command line.
 175.SP
 176If a command has two names (e.g., \fBcheckout\fR and
 177\fBco\fR), the official name, not necessarily the one
 178used on the command line, will be used to match against
 179the 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
 185log -N
 186.IP "" 2
 187diff -uN
 188.IP "" 2
 189rdiff -u
 190.IP "" 2
 191update -Pd
 192.IP "" 2
 193checkout -P
 194.IP "" 2
 195release -d
 196
 197.PD
 198.IP "" 0
 199.SP
 200the 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
 204With the example file above, the output from \fBcvs
 205diff foobar\fR will be in unidiff format.  \fBcvs diff
 206-c foobar\fR will provide context diffs, as usual.
 207Getting "old" format diffs would be slightly more
 208complicated, because \fBdiff\fR doesn\(aqt have an option
 209to specify use of the "old" format, so you would need
 210\fBcvs -f diff foobar\fR.
 211.SP
 212In place of the command name you can use \fBcvs\fR to
 213specify global options (see node `Global options\(aq in the CVS manual).  For
 214example the following line in \fB.cvsrc\fR
 215.SP
 216.PD 0
 217.SP
 218.IP "" 2
 219cvs -z6
 220
 221.PD
 222.IP "" 0
 223.SP
 224causes \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
 231The available \fBcvs_options\fR (that are given to the
 232left of \fBcvs_command\fR) are:
 233.SP
 234.IP "" 0
 235\fB--allow-root=\fIrootdir\fB\fR
 236.IP "" 2
 237Specify legal \fBcvsroot\fR directory.  See
 238`Password authentication server\(aq in the CVS manual.
 239.SP
 240.IX "Authentication, stream"
 241.IX "Stream authentication"
 242.IP "" 0
 243\fB-a\fR
 244.IP "" 2
 245Authenticate all communication between the client and
 246the server.  Only has an effect on the \fBcvs\fR client.
 247As of this writing, this is only implemented when using
 248a GSSAPI connection (see node `GSSAPI authenticated\(aq in the CVS manual).
 249Authentication prevents certain sorts of attacks
 250involving hijacking the active \fBtcp\fR connection.
 251Enabling authentication does not enable encryption.
 252.SP
 253.IX "RCSBIN, overriding"
 254.IX "Overriding RCSBIN"
 255.IP "" 0
 256\fB-b \fIbindir\fB\fR
 257.IP "" 2
 258In \fBcvs\fR 1.9.18 and older, this specified that
 259\fBrcs\fR programs are in the \fIbindir\fR directory.
 260Current versions of \fBcvs\fR do not run \fBrcs\fR
 261programs; for compatibility this option is accepted,
 262but it does nothing.
 263.SP
 264.IX "TMPDIR, overriding"
 265.IX "Overriding TMPDIR"
 266.IP "" 0
 267\fB-T \fItempdir\fB\fR
 268.IP "" 2
 269Use \fItempdir\fR as the directory where temporary files are
 270located.  Overrides the setting of the \fB$TMPDIR\fR environment
 271variable and any precompiled directory.  This parameter should be
 272specified as an absolute pathname.
 273(When running client/server, \fB-T\fR affects only the local process;
 274specifying \fB-T\fR for the client has no effect on the server and
 275vice versa.)
 276.SP
 277.IX "CVSROOT, overriding"
 278.IX "Overriding CVSROOT"
 279.IP "" 0
 280\fB-d \fIcvs_root_directory\fB\fR
 281.IP "" 2
 282Use \fIcvs_root_directory\fR as the root directory
 283pathname of the repository.  Overrides the setting of
 284the \fB$CVSROOT\fR environment variable.  See `Repository\(aq in the CVS manual.
 285.SP
 286.IX "EDITOR, overriding"
 287.IX "Overriding EDITOR"
 288.IP "" 0
 289\fB-e \fIeditor\fB\fR
 290.IP "" 2
 291Use \fIeditor\fR to enter revision log information.  Overrides the
 292setting of the \fB$CVSEDITOR\fR and \fB$EDITOR\fR
 293environment variables.  For more information, see
 294`Committing your changes\(aq in the CVS manual.
 295.SP
 296.IP "" 0
 297\fB-f\fR
 298.IP "" 2
 299Do not read the \fB~/.cvsrc\fR file.  This
 300option is most often used because of the
 301non-orthogonality of the \fBcvs\fR option set.  For
 302example, the \fBcvs log\fR option \fB-N\fR (turn off
 303display of tag names) does not have a corresponding
 304option to turn the display on.  So if you have
 305\fB-N\fR in the \fB~/.cvsrc\fR entry for \fBlog\fR,
 306you may need to use \fB-f\fR to show the tag names.
 307.SP
 308.IP "" 0
 309\fB-H\fR
 310.IP "" 2
 311.IP "" 0
 312\fB--help\fR
 313.IP "" 2
 314Display usage information about the specified \fBcvs_command\fR
 315(but do not actually execute the command).  If you don\(aqt specify
 316a command name, \fBcvs -H\fR displays overall help for
 317\fBcvs\fR, including a list of other help options.
 318.SP
 319.IX "Read-only mode"
 320.IP "" 0
 321\fB-n\fR
 322.IP "" 2
 323Do not change any files.  Attempt to execute the
 324\fBcvs_command\fR, but only to issue reports; do not remove,
 325update, or merge any existing files, or create any new files.
 326.SP
 327Note that \fBcvs\fR will not necessarily produce exactly
 328the same output as without \fB-n\fR.  In some cases
 329the output will be the same, but in other cases
 330\fBcvs\fR will skip some of the processing that would
 331have been required to produce the exact same output.
 332.SP
 333.IP "" 0
 334\fB-Q\fR
 335.IP "" 2
 336Cause the command to be really quiet; the command will only
 337generate output for serious problems.
 338.SP
 339.IP "" 0
 340\fB-q\fR
 341.IP "" 2
 342Cause the command to be somewhat quiet; informational messages,
 343such as reports of recursion through subdirectories, are
 344suppressed.
 345.SP
 346.IX "Read-only files, and -r"
 347.IP "" 0
 348\fB-r\fR
 349.IP "" 2
 350Make new working files read-only.  Same effect
 351as if the \fB$CVSREAD\fR environment variable is set
 352(see node `Environment variables\(aq in the CVS manual).  The default is to
 353make working files writable, unless watches are on
 354(see node `Watches\(aq in the CVS manual).
 355.SP
 356.IP "" 0
 357\fB-s \fIvariable\fB=\fIvalue\fB\fR
 358.IP "" 2
 359Set a user variable (see node `Variables\(aq in the CVS manual).
 360.SP
 361.IX "Trace"
 362.IP "" 0
 363\fB-t\fR
 364.IP "" 2
 365Trace program execution; display messages showing the steps of
 366\fBcvs\fR activity.  Particularly useful with \fB-n\fR to explore the
 367potential impact of an unfamiliar command.
 368.SP
 369.IP "" 0
 370\fB-v\fR
 371.IP "" 2
 372.IP "" 0
 373\fB--version\fR
 374.IP "" 2
 375Display version and copyright information for \fBcvs\fR.
 376.SP
 377.IX "CVSREAD, overriding"
 378.IX "Overriding CVSREAD"
 379.IP "" 0
 380\fB-w\fR
 381.IP "" 2
 382Make new working files read-write.  Overrides the
 383setting of the \fB$CVSREAD\fR environment variable.
 384Files are created read-write by default, unless \fB$CVSREAD\fR is
 385set or \fB-r\fR is given.
 386.SP
 387.IP "" 0
 388\fB-x\fR
 389.IP "" 2
 390.IX "Encryption"
 391Encrypt all communication between the client and the
 392server.  Only has an effect on the \fBcvs\fR client.  As
 393of this writing, this is only implemented when using a
 394GSSAPI connection (see node `GSSAPI authenticated\(aq in the CVS manual) or a
 395Kerberos connection (see node `Kerberos authenticated\(aq in the CVS manual).
 396Enabling encryption implies that message traffic is
 397also authenticated.  Encryption support is not
 398available by default; it must be enabled using a
 399special configure option, \fB--enable-encryption\fR,
 400when you build \fBcvs\fR.
 401.SP
 402.IP "" 0
 403\fB-z \fIgzip-level\fB\fR
 404.IP "" 2
 405.IX "Compression"
 406.IX "Gzip"
 407Set the compression level.
 408Valid levels are 1 (high speed, low compression) to
 4099 (low speed, high compression), or 0 to disable
 410compression (the default).
 411Only has an effect on the \fBcvs\fR client.
 412.SP
 413.SP
 414.SH "Common options"
 415.SS "Common command options"
 416.IX "Common options"
 417.IX "Right-hand options"
 418.SP
 419This section describes the \fBcommand_options\fR that
 420are available across several \fBcvs\fR commands.  These
 421options are always given to the right of
 422\fBcvs_command\fR. Not all
 423commands support all of these options; each option is
 424only supported for commands where it makes sense.
 425However, when a command has one of these options you
 426can almost always count on the same behavior of the
 427option as in other commands.  (Other command options,
 428which are listed with the individual commands, may have
 429different behavior from one \fBcvs\fR command to the other).
 430.SP
 431\fBThe \fBhistory\fB command is an exception; it supports
 432many options that conflict even with these standard options.\fR
 433.SP
 434.IX "Dates"
 435.IX "Time"
 436.IX "Specifying dates"
 437.IP "" 0
 438\fB-D \fIdate_spec\fB\fR
 439.IP "" 2
 440Use the most recent revision no later than \fIdate_spec\fR.
 441\fIdate_spec\fR is a single argument, a date description
 442specifying a date in the past.
 443.SP
 444The specification is \fIsticky\fR when you use it to make a
 445private copy of a source file; that is, when you get a working
 446file using \fB-D\fR, \fBcvs\fR records the date you specified, so that
 447further updates in the same directory will use the same date
 448(for more information on sticky tags/dates, see node `Sticky tags\(aq in the CVS manual).
 449.SP
 450\fB-D\fR is available with the \fBannotate\fR, \fBcheckout\fR,
 451\fBdiff\fR, \fBexport\fR, \fBhistory\fR,
 452\fBrdiff\fR, \fBrtag\fR, and \fBupdate\fR commands.
 453(The \fBhistory\fR command uses this option in a
 454slightly different way; see node `history options\(aq in the CVS manual).
 455.SP
 456.IX "Timezone, in input"
 457.IX "Zone, time, in input"
 458A wide variety of date formats are supported by
 459\fBcvs\fR.  The most standard ones are ISO8601 (from the
 460International Standards Organization) and the Internet
 461e-mail standard (specified in RFC822 as amended by
 462RFC1123).
 463.SP
 464ISO8601 dates have many variants but a few examples
 465are:
 466.SP
 467.PD 0
 468.SP
 469.IP "" 4
 4701972-09-24
 471.IP "" 4
 4721972-09-24 20:05
 473
 474.PD
 475.IP "" 2
 476.SP
 477There are a lot more ISO8601 date formats, and \fBcvs\fR
 478accepts many of them, but you probably don\(aqt want to
 479hear the \fIwhole\fR long story :-).
 480.SP
 481In addition to the dates allowed in Internet e-mail
 482itself, \fBcvs\fR also allows some of the fields to be
 483omitted.  For example:
 484.SP
 485.PD 0
 486.SP
 487.IP "" 4
 48824 Sep 1972 20:05
 489.IP "" 4
 49024 Sep
 491
 492.PD
 493.IP "" 2
 494.SP
 495The date is interpreted as being in the
 496local timezone, unless a specific timezone is
 497specified.
 498.SP
 499These two date formats are preferred.  However,
 500\fBcvs\fR currently accepts a wide variety of other date
 501formats.  They are intentionally not documented here in
 502any detail, and future versions of \fBcvs\fR might not
 503accept all of them.
 504.SP
 505One such format is
 506\fB\fImonth\fB/\fIday\fB/\fIyear\fB\fR.  This may
 507confuse people who are accustomed to having the month
 508and day in the other order; \fB1/4/96\fR is January 4,
 509not April 1.
 510.SP
 511Remember to quote the argument to the \fB-D\fR
 512flag so that your shell doesn\(aqt interpret spaces as
 513argument separators.  A command using the \fB-D\fR
 514flag can look like this:
 515.SP
 516.PD 0
 517.SP
 518.IP "" 4
 519$ cvs diff -D "1 hour ago" cvs.texinfo
 520
 521.PD
 522.IP "" 2
 523.SP
 524.IX "Forcing a tag match"
 525.IP "" 0
 526\fB-f\fR
 527.IP "" 2
 528When you specify a particular date or tag to \fBcvs\fR commands, they
 529normally ignore files that do not contain the tag (or did not
 530exist prior to the date) that you specified.  Use the \fB-f\fR option
 531if you want files retrieved even when there is no match for the
 532tag or date.  (The most recent revision of the file
 533will be used).
 534.SP
 535Note that even with \fB-f\fR, a tag that you specify
 536must exist (that is, in some file, not necessary in
 537every file).  This is so that \fBcvs\fR will continue to
 538give an error if you mistype a tag name.
 539.SP
 540\fB-f\fR is available with these commands:
 541\fBannotate\fR, \fBcheckout\fR, \fBexport\fR,
 542\fBrdiff\fR, \fBrtag\fR, and \fBupdate\fR.
 543.SP
 544\fBWARNING:  The \fBcommit\fB and \fBremove\fB
 545commands also have a
 546\fB-f\fB option, but it has a different behavior for
 547those commands.  See `commit options\(aq in the CVS manual, and
 548`Removing files\(aq in the CVS manual.\fR
 549.SP
 550.IP "" 0
 551\fB-k \fIkflag\fB\fR
 552.IP "" 2
 553Alter the default processing of keywords.
 554See `Keyword substitution\(aq in the CVS manual, for the meaning of
 555\fIkflag\fR.  Your \fIkflag\fR specification is
 556\fIsticky\fR when you use it to create a private copy
 557of a source file; that is, when you use this option
 558with the \fBcheckout\fR or \fBupdate\fR commands,
 559\fBcvs\fR associates your selected \fIkflag\fR with the
 560file, and continues to use it with future update
 561commands on the same file until you specify otherwise.
 562.SP
 563The \fB-k\fR option is available with the \fBadd\fR,
 564\fBcheckout\fR, \fBdiff\fR, \fBrdiff\fR, \fBimport\fR and
 565\fBupdate\fR commands.
 566.SP
 567.IP "" 0
 568\fB-l\fR
 569.IP "" 2
 570Local; run only in current working directory, rather than
 571recursing through subdirectories.
 572.SP
 573Available with the following commands: \fBannotate\fR, \fBcheckout\fR,
 574\fBcommit\fR, \fBdiff\fR, \fBedit\fR, \fBeditors\fR, \fBexport\fR,
 575\fBlog\fR, \fBrdiff\fR, \fBremove\fR, \fBrtag\fR,
 576\fBstatus\fR, \fBtag\fR, \fBunedit\fR, \fBupdate\fR, \fBwatch\fR,
 577and \fBwatchers\fR.
 578.SP
 579.IX "Editor, avoiding invocation of"
 580.IX "Avoiding editor invocation"
 581.IP "" 0
 582\fB-m \fImessage\fB\fR
 583.IP "" 2
 584Use \fImessage\fR as log information, instead of
 585invoking an editor.
 586.SP
 587Available with the following commands: \fBadd\fR,
 588\fBcommit\fR and \fBimport\fR.
 589.SP
 590.IP "" 0
 591\fB-n\fR
 592.IP "" 2
 593Do not run any tag program.  (A program can be
 594specified to run in the modules
 595database (see node `modules\(aq in the CVS manual); this option bypasses it).
 596.SP
 597\fBThis is not the same as the \fBcvs -n\fB
 598program option, which you can specify to the left of a cvs command!\fR
 599.SP
 600Available with the \fBcheckout\fR, \fBexport\fR,
 601and \fBrtag\fR commands.
 602.SP
 603.IP "" 0
 604\fB-P\fR
 605.IP "" 2
 606Prune empty directories.  See `Removing directories\(aq in the CVS manual.
 607.SP
 608.IP "" 0
 609\fB-p\fR
 610.IP "" 2
 611Pipe the files retrieved from the repository to standard output,
 612rather than writing them in the current directory.  Available
 613with the \fBcheckout\fR and \fBupdate\fR commands.
 614.SP
 615.IP "" 0
 616\fB-R\fR
 617.IP "" 2
 618Process directories recursively.  This is on by default.
 619.SP
 620Available with the following commands: \fBannotate\fR, \fBcheckout\fR,
 621\fBcommit\fR, \fBdiff\fR, \fBedit\fR, \fBeditors\fR, \fBexport\fR,
 622\fBrdiff\fR, \fBremove\fR, \fBrtag\fR,
 623\fBstatus\fR, \fBtag\fR, \fBunedit\fR, \fBupdate\fR, \fBwatch\fR,
 624and \fBwatchers\fR.
 625.SP
 626.IP "" 0
 627\fB-r \fItag\fB\fR
 628.IP "" 2
 629.IX "HEAD, special tag"
 630.IX "BASE, special tag"
 631Use the revision specified by the \fItag\fR argument instead of the
 632default \fIhead\fR revision.  As well as arbitrary tags defined
 633with the \fBtag\fR or \fBrtag\fR command, two special tags are
 634always available: \fBHEAD\fR refers to the most recent version
 635available in the repository, and \fBBASE\fR refers to the
 636revision you last checked out into the current working directory.
 637.SP
 638The tag specification is sticky when you use this
 639with \fBcheckout\fR or \fBupdate\fR to make your own
 640copy of a file: \fBcvs\fR remembers the tag and continues to use it on
 641future update commands, until you specify otherwise (for more information
 642on sticky tags/dates, see node `Sticky tags\(aq in the CVS manual).
 643.SP
 644The tag can be either a symbolic or numeric tag, as
 645described in `Tags\(aq in the CVS manual, or the name of a branch, as
 646described in `Branching and merging\(aq in the CVS manual.
 647When a command expects a specific revision,
 648the name of a branch is interpreted as the most recent
 649revision on that branch.
 650.SP
 651Specifying the \fB-q\fR global option along with the
 652\fB-r\fR command option is often useful, to suppress
 653the warning messages when the \fBrcs\fR file
 654does not contain the specified tag.
 655.SP
 656\fBThis is not the same as the overall \fBcvs -r\fB option,
 657which you can specify to the left of a \fBcvs\fB command!\fR
 658.SP
 659\fB-r\fR is available with the \fBannotate\fR, \fBcheckout\fR,
 660\fBcommit\fR, \fBdiff\fR, \fBhistory\fR, \fBexport\fR, \fBrdiff\fR, 
 661\fBrtag\fR, and \fBupdate\fR commands.
 662.SP
 663.IP "" 0
 664\fB-W\fR
 665.IP "" 2
 666Specify file names that should be filtered.  You can
 667use this option repeatedly.  The spec can be a file
 668name pattern of the same type that you can specify in
 669the \fB.cvswrappers\fR file.
 670Available with the following commands: \fBimport\fR,
 671and \fBupdate\fR.
 672.SP
 673.SP
 674.SH "add"
 675.SS "Add files and directories to the repository"
 676.IX "add (subcommand)"
 677.SP
 678.IP "\(bu" 2
 679Synopsis: add [-k rcs-kflag] [-m message] files...
 680.IP "\(bu" 2
 681Requires: repository, working directory.
 682.IP "\(bu" 2
 683Changes: repository, working directory.
 684.SP
 685The \fBadd\fR command is used to present new files
 686and directories for addition into the \fBcvs\fR
 687repository.  When \fBadd\fR is used on a directory,
 688a new directory is created in the repository
 689immediately.  When used on a file, only the working
 690directory is updated.  Changes to the repository are
 691not made until the \fBcommit\fR command is used on
 692the newly added file. 
 693.SP
 694The \fBadd\fR command also resurrects files that
 695have been previously removed.  This can be done
 696before or after the \fBcommit\fR command is used
 697to finalize the removal of files.  Resurrected files
 698are restored into the working directory at the time
 699the \fBadd\fR command is executed.
 700.SP
 701.SH "add options"
 702.SP
 703These standard options are supported by \fBadd\fR
 704(see node `Common options\(aq in the CVS manual, for a complete description of
 705them):
 706.SP
 707.IP "" 0
 708\fB-k \fIkflag\fB\fR
 709.IP "" 2
 710Process keywords according to \fIkflag\fR.  See
 711`Keyword substitution\(aq in the CVS manual.
 712This option is sticky; future updates of
 713this file in this working directory will use the same
 714\fIkflag\fR.  The \fBstatus\fR command can be viewed
 715to see the sticky options.  For more information on
 716the \fBstatus\fR command, see node `Invoking CVS\(aq in the CVS manual.
 717.SP
 718.IP "" 0
 719\fB-m \fImessage\fB\fR
 720.IP "" 2
 721Use \fImessage\fR as the log message, instead of
 722invoking an editor.
 723.SP
 724.SH "add examples"
 725.SP
 726.SS "Adding a directory"
 727.SP
 728.PD 0
 729.SP
 730.IP "" 2
 731$ mkdir doc
 732.IP "" 2
 733$ cvs add doc
 734.IP "" 2
 735Directory /path/to/repository/doc added to the repository
 736
 737.PD
 738.IP "" 0
 739.SP
 740.SS "Adding a file"
 741.SP
 742.PD 0
 743.SP
 744.SP
 745.IP "" 2
 746$ >TODO
 747.IP "" 2
 748$ cvs add TODO
 749.IP "" 2
 750cvs add: scheduling file \`TODO\(aq for addition
 751.IP "" 2
 752cvs add: use \(aqcvs commit\(aq to add this file permanently
 753
 754.PD
 755.IP "" 0
 756.SP
 757.SS "Undoing a \fBremove\fR command"
 758.SP
 759.PD 0
 760.SP
 761.IP "" 2
 762$ rm -f makefile
 763.IP "" 2
 764$ cvs remove makefile
 765.IP "" 2
 766cvs remove: scheduling \`makefile\(aq for removal
 767.IP "" 2
 768cvs remove: use \(aqcvs commit\(aq to remove this file permanently
 769.IP "" 2
 770$ cvs add makefile
 771.IP "" 2
 772U makefile
 773.IP "" 2
 774cvs add: makefile, version 1.2, resurrected
 775
 776.PD
 777.IP "" 0
 778.SP
 779.SH "admin"
 780.SS "Administration"
 781.IX "Admin (subcommand)"
 782.SP
 783.IP "\(bu" 2
 784Requires: repository, working directory.
 785.IP "\(bu" 2
 786Changes: repository.
 787.IP "\(bu" 2
 788Synonym: rcs
 789.SP
 790This is the \fBcvs\fR interface to assorted
 791administrative facilities.  Some of them have
 792questionable usefulness for \fBcvs\fR but exist for
 793historical purposes.  Some of the questionable options
 794are likely to disappear in the future.  This command
 795\fIdoes\fR work recursively, so extreme care should be
 796used.
 797.SP
 798.IX "cvsadmin"
 799On unix, if there is a group named \fBcvsadmin\fR,
 800only members of that group can run \fBcvs admin\fR
 801(except for the \fBcvs admin -k\fR command, which can
 802be run by anybody).  This group should exist on the
 803server, or any system running the non-client/server
 804\fBcvs\fR.  To disallow \fBcvs admin\fR for all users,
 805create a group with no users in it.  On NT, the
 806\fBcvsadmin\fR feature does not exist and all users
 807can run \fBcvs admin\fR.
 808.SP
 809.SH "admin options"
 810.SP
 811Some of these options have questionable usefulness for
 812\fBcvs\fR but exist for historical purposes.  Some even
 813make it impossible to use \fBcvs\fR until you undo the
 814effect!
 815.SP
 816.IP "" 0
 817\fB-A\fIoldfile\fB\fR
 818.IP "" 2
 819Might not work together with \fBcvs\fR.  Append the
 820access list of \fIoldfile\fR to the access list of the
 821\fBrcs\fR file.
 822.SP
 823.IP "" 0
 824\fB-a\fIlogins\fB\fR
 825.IP "" 2
 826Might not work together with \fBcvs\fR.  Append the
 827login names appearing in the comma-separated list
 828\fIlogins\fR to the access list of the \fBrcs\fR file.
 829.SP
 830.IP "" 0
 831\fB-b[\fIrev\fB]\fR
 832.IP "" 2
 833Set the default branch to \fIrev\fR.  In \fBcvs\fR, you
 834normally do not manipulate default branches; sticky
 835tags (see node `Sticky tags\(aq in the CVS manual) are a better way to decide
 836which branch you want to work on.  There is one reason
 837to run \fBcvs admin -b\fR: to revert to the vendor\(aqs
 838version when using vendor branches (see node `Reverting
 839local changes\(aq in the CVS manual).
 840There can be no space between \fB-b\fR and its argument.
 841.SP
 842.IX "Comment leader"
 843.IP "" 0
 844\fB-c\fIstring\fB\fR
 845.IP "" 2
 846Sets the comment leader to \fIstring\fR.  The comment
 847leader is not used by current versions of \fBcvs\fR or
 848\fBrcs\fR 5.7.  Therefore, you can almost surely not
 849worry about it.  See `Keyword substitution\(aq in the CVS manual.
 850.SP
 851.IP "" 0
 852\fB-e[\fIlogins\fB]\fR
 853.IP "" 2
 854Might not work together with \fBcvs\fR.  Erase the login
 855names appearing in the comma-separated list
 856\fIlogins\fR from the access list of the RCS file.  If
 857\fIlogins\fR is omitted, erase the entire access list.
 858There can be no space between \fB-e\fR and its argument.
 859.SP
 860.IP "" 0
 861\fB-I\fR
 862.IP "" 2
 863Run interactively, even if the standard input is not a
 864terminal.  This option does not work with the
 865client/server \fBcvs\fR and is likely to disappear in
 866a future release of \fBcvs\fR.
 867.SP
 868.IP "" 0
 869\fB-i\fR
 870.IP "" 2
 871Useless with \fBcvs\fR.  This creates and initializes a
 872new \fBrcs\fR file, without depositing a revision.  With
 873\fBcvs\fR, add files with the \fBcvs add\fR command
 874(see node `Adding files\(aq in the CVS manual).
 875.SP
 876.IP "" 0
 877\fB-k\fIsubst\fB\fR
 878.IP "" 2
 879Set the default keyword
 880substitution to \fIsubst\fR.  See `Keyword
 881substitution\(aq in the CVS manual.  Giving an explicit \fB-k\fR option to
 882\fBcvs update\fR, \fBcvs export\fR, or \fBcvs
 883checkout\fR overrides this default.
 884.SP
 885.IP "" 0
 886\fB-l[\fIrev\fB]\fR
 887.IP "" 2
 888Lock the revision with number \fIrev\fR.  If a branch
 889is given, lock the latest revision on that branch.  If
 890\fIrev\fR is omitted, lock the latest revision on the
 891default branch.  There can be no space between
 892\fB-l\fR and its argument.
 893.SP
 894This can be used in conjunction with the
 895\fBrcslock.pl\fR script in the \fBcontrib\fR
 896directory of the \fBcvs\fR source distribution to
 897provide reserved checkouts (where only one user can be
 898editing a given file at a time).  See the comments in
 899that file for details (and see the \fBREADME\fR file
 900in that directory for disclaimers about the unsupported
 901nature of contrib).  According to comments in that
 902file, locking must set to strict (which is the default).
 903.SP
 904.IP "" 0
 905\fB-L\fR
 906.IP "" 2
 907Set locking to strict.  Strict locking means that the
 908owner of an RCS file is not exempt from locking for
 909checkin.  For use with \fBcvs\fR, strict locking must be
 910set; see the discussion under the \fB-l\fR option above.
 911.SP
 912.IX "Changing a log message"
 913.IX "Replacing a log message"
 914.IX "Correcting a log message"
 915.IX "Fixing a log message"
 916.IX "Log message, correcting"
 917.IP "" 0
 918\fB-m\fIrev\fB:\fImsg\fB\fR
 919.IP "" 2
 920Replace the log message of revision \fIrev\fR with
 921\fImsg\fR.
 922.SP
 923.IP "" 0
 924\fB-N\fIname\fB[:[\fIrev\fB]]\fR
 925.IP "" 2
 926Act like \fB-n\fR, except override any previous
 927assignment of \fIname\fR.  For use with magic branches,
 928see `Magic branch numbers\(aq in the CVS manual.
 929.SP
 930.IP "" 0
 931\fB-n\fIname\fB[:[\fIrev\fB]]\fR
 932.IP "" 2
 933Associate the symbolic name \fIname\fR with the branch
 934or revision \fIrev\fR.  It is normally better to use
 935\fBcvs tag\fR or \fBcvs rtag\fR instead.  Delete the
 936symbolic name if both \fB:\fR and \fIrev\fR are
 937omitted; otherwise, print an error message if
 938\fIname\fR is already associated with another number.
 939If \fIrev\fR is symbolic, it is expanded before
 940association.  A \fIrev\fR consisting of a branch number
 941followed by a \fB.\fR stands for the current latest
 942revision in the branch.  A \fB:\fR with an empty
 943\fIrev\fR stands for the current latest revision on the
 944default branch, normally the trunk.  For example,
 945\fBcvs admin -n\fIname\fB:\fR associates \fIname\fR with the
 946current latest revision of all the RCS files;
 947this contrasts with \fBcvs admin -n\fIname\fB:$\fR which
 948associates \fIname\fR with the revision numbers
 949extracted from keyword strings in the corresponding
 950working files.
 951.SP
 952.IX "Deleting revisions"
 953.IX "Outdating revisions"
 954.IX "Saving space"
 955.IP "" 0
 956\fB-o\fIrange\fB\fR
 957.IP "" 2
 958Deletes (\fIoutdates\fR) the revisions given by
 959\fIrange\fR.
 960.SP
 961Note that this command can be quite dangerous unless
 962you know \fIexactly\fR what you are doing (for example
 963see the warnings below about how the
 964\fIrev1\fR:\fIrev2\fR syntax is confusing).
 965.SP
 966If you are short on disc this option might help you.
 967But think twice before using it\(emthere is no way short
 968of restoring the latest backup to undo this command!
 969If you delete different revisions than you planned,
 970either due to carelessness or (heaven forbid) a \fBcvs\fR
 971bug, there is no opportunity to correct the error
 972before the revisions are deleted.  It probably would be
 973a good idea to experiment on a copy of the repository
 974first.
 975.SP
 976Specify \fIrange\fR in one of the following ways:
 977.SP
 978.IP "" 2
 979\fB\fIrev1\fB::\fIrev2\fB\fR
 980.IP "" 4
 981Collapse all revisions between rev1 and rev2, so that
 982\fBcvs\fR only stores the differences associated with going
 983from rev1 to rev2, not intermediate steps.  For
 984example, after \fB-o 1.3::1.5\fR one can retrieve
 985revision 1.3, revision 1.5, or the differences to get
 986from 1.3 to 1.5, but not the revision 1.4, or the
 987differences between 1.3 and 1.4.  Other examples:
 988\fB-o 1.3::1.4\fR and \fB-o 1.3::1.3\fR have no
 989effect, because there are no intermediate revisions to
 990remove.
 991.SP
 992.IP "" 2
 993\fB::\fIrev\fB\fR
 994.IP "" 4
 995Collapse revisions between the beginning of the branch
 996containing \fIrev\fR and \fIrev\fR itself.  The
 997branchpoint and \fIrev\fR are left intact.  For
 998example, \fB-o ::1.3.2.6\fR deletes revision 1.3.2.1,
 999revision 1.3.2.5, and everything in between, but leaves
10001.3 and 1.3.2.6 intact.
1001.SP
1002.IP "" 2
1003\fB\fIrev\fB::\fR
1004.IP "" 4
1005Collapse revisions between \fIrev\fR and the end of the
1006branch containing \fIrev\fR.  Revision \fIrev\fR is
1007left intact but the head revision is deleted.
1008.SP
1009.IP "" 2
1010\fB\fIrev\fB\fR
1011.IP "" 4
1012Delete the revision \fIrev\fR.  For example, \fB-o
10131.3\fR is equivalent to \fB-o 1.2::1.4\fR.
1014.SP
1015.IP "" 2
1016\fB\fIrev1\fB:\fIrev2\fB\fR
1017.IP "" 4
1018Delete the revisions from \fIrev1\fR to \fIrev2\fR,
1019inclusive, on the same branch.  One will not be able to
1020retrieve \fIrev1\fR or \fIrev2\fR or any of the
1021revisions in between.  For example, the command
1022\fBcvs admin -oR_1_01:R_1_02 \&.\fR is rarely useful.
1023It means to delete revisions up to, and including, the
1024tag R_1_02.  But beware!  If there are files that have not
1025changed between R_1_02 and R_1_03 the file will have
1026\fIthe same\fR numerical revision number assigned to
1027the tags R_1_02 and R_1_03.  So not only will it be
1028impossible to retrieve R_1_02; R_1_03 will also have to
1029be restored from the tapes!  In most cases you want to
1030specify \fIrev1\fR::\fIrev2\fR instead.
1031.SP
1032.IP "" 2
1033\fB:\fIrev\fB\fR
1034.IP "" 4
1035Delete revisions from the beginning of the
1036branch containing \fIrev\fR up to and including
1037\fIrev\fR.
1038.SP
1039.IP "" 2
1040\fB\fIrev\fB:\fR
1041.IP "" 4
1042Delete revisions from revision \fIrev\fR, including
1043\fIrev\fR itself, to the end of the branch containing
1044\fIrev\fR.
1045.SP
1046None of the revisions to be deleted may have
1047branches or locks.
1048.SP
1049If any of the revisions to be deleted have symbolic
1050names, and one specifies one of the \fB::\fR syntaxes,
1051then \fBcvs\fR will give an error and not delete any
1052revisions.  If you really want to delete both the
1053symbolic names and the revisions, first delete the
1054symbolic names with \fBcvs tag -d\fR, then run
1055\fBcvs admin -o\fR.  If one specifies the
1056non-\fB::\fR syntaxes, then \fBcvs\fR will delete the
1057revisions but leave the symbolic names pointing to
1058nonexistent revisions.  This behavior is preserved for
1059compatibility with previous versions of \fBcvs\fR, but
1060because it isn\(aqt very useful, in the future it may
1061change to be like the \fB::\fR case.
1062.SP
1063Due to the way \fBcvs\fR handles branches \fIrev\fR
1064cannot be specified symbolically if it is a branch.
1065See `Magic branch numbers\(aq in the CVS manual for an explanation.
1066.SP
1067Make sure that no-one has checked out a copy of the
1068revision you outdate.  Strange things will happen if he
1069starts to edit it and tries to check it back in.  For
1070this reason, this option is not a good way to take back
1071a bogus commit; commit a new revision undoing the bogus
1072change instead (see node `Merging two revisions\(aq in the CVS manual).
1073.SP
1074.IP "" 0
1075\fB-q\fR
1076.IP "" 2
1077Run quietly; do not print diagnostics.
1078.SP
1079.IP "" 0
1080\fB-s\fIstate\fB[:\fIrev\fB]\fR
1081.IP "" 2
1082Useful with \fBcvs\fR.  Set the state attribute of the
1083revision \fIrev\fR to \fIstate\fR.  If \fIrev\fR is a
1084branch number, assume the latest revision on that
1085branch.  If \fIrev\fR is omitted, assume the latest
1086revision on the default branch.  Any identifier is
1087acceptable for \fIstate\fR.  A useful set of states is
1088\fBExp\fR (for experimental), \fBStab\fR (for
1089stable), and \fBRel\fR (for released).  By default,
1090the state of a new revision is set to \fBExp\fR when
1091it is created.  The state is visible in the output from
1092\fIcvs log\fR (see node `log\(aq in the CVS manual), and in the
1093\fB$\fP\fPLog$\fR and \fB$\fP\fPState$\fR keywords
1094(see node `Keyword substitution\(aq in the CVS manual).  Note that \fBcvs\fR
1095uses the \fBdead\fR state for its own purposes (see node `Attic\(aq in the CVS manual); to
1096take a file to or from the \fBdead\fR state use
1097commands like \fBcvs remove\fR and \fBcvs add\fR
1098(see node `Adding and removing\(aq in the CVS manual), not \fBcvs admin -s\fR.
1099.SP
1100.IP "" 0
1101\fB-t[\fIfile\fB]\fR
1102.IP "" 2
1103Useful with \fBcvs\fR.  Write descriptive text from the
1104contents of the named \fIfile\fR into the RCS file,
1105deleting the existing text.  The \fIfile\fR pathname
1106may not begin with \fB-\fR.  The descriptive text can be seen in the
1107output from \fBcvs log\fR (see node `log\(aq in the CVS manual).
1108There can be no space between \fB-t\fR and its argument.
1109.SP
1110If \fIfile\fR is omitted,
1111obtain the text from standard input, terminated by
1112end-of-file or by a line containing \fB.\fR by itself.
1113Prompt for the text if interaction is possible; see
1114\fB-I\fR.
1115.SP
1116.IP "" 0
1117\fB-t-\fIstring\fB\fR
1118.IP "" 2
1119Similar to \fB-t\fIfile\fB\fR. Write descriptive text
1120from the \fIstring\fR into the \fBrcs\fR file, deleting
1121the existing text.
1122There can be no space between \fB-t\fR and its argument.
1123.SP
1124.IP "" 0
1125\fB-U\fR
1126.IP "" 2
1127Set locking to non-strict.  Non-strict locking means
1128that the owner of a file need not lock a revision for
1129checkin.  For use with \fBcvs\fR, strict locking must be
1130set; see the discussion under the \fB-l\fR option
1131above.
1132.SP
1133.IP "" 0
1134\fB-u[\fIrev\fB]\fR
1135.IP "" 2
1136See the option \fB-l\fR above, for a discussion of
1137using this option with \fBcvs\fR.  Unlock the revision
1138with number \fIrev\fR.  If a branch is given, unlock
1139the latest revision on that branch.  If \fIrev\fR is
1140omitted, remove the latest lock held by the caller.
1141Normally, only the locker of a revision may unlock it;
1142somebody else unlocking a revision breaks the lock.
1143This causes the original locker to be sent a \fBcommit\fR
1144notification (see node `Getting Notified\(aq in the CVS manual).
1145There can be no space between \fB-u\fR and its argument.
1146.SP
1147.IP "" 0
1148\fB-V\fIn\fB\fR
1149.IP "" 2
1150In previous versions of \fBcvs\fR, this option meant to
1151write an \fBrcs\fR file which would be acceptable to
1152\fBrcs\fR version \fIn\fR, but it is now obsolete and
1153specifying it will produce an error.
1154.SP
1155.IP "" 0
1156\fB-x\fIsuffixes\fB\fR
1157.IP "" 2
1158In previous versions of \fBcvs\fR, this was documented
1159as a way of specifying the names of the \fBrcs\fR
1160files.  However, \fBcvs\fR has always required that the
1161\fBrcs\fR files used by \fBcvs\fR end in \fB,v\fR, so
1162this option has never done anything useful.
1163.SP
1164.SP
1165.SH "annotate"
1166.SS "What revision modified each line of a file?"
1167.IX "annotate (subcommand)"
1168.SP
1169.IP "\(bu" 2
1170Synopsis: annotate [options] files\&...
1171.IP "\(bu" 2
1172Requires: repository.
1173.IP "\(bu" 2
1174Synonym: blame
1175.IP "\(bu" 2
1176Changes: nothing.
1177.SP
1178For each file in \fIfiles\fR, print the head revision
1179of the trunk, together with information on the last
1180modification for each line.  
1181.SP
1182.SH "annotate options"
1183.SP
1184These standard options are supported by \fBannotate\fR
1185(see node `Common options\(aq in the CVS manual for a complete description of
1186them):
1187.SP
1188.IP "" 0
1189\fB-l\fR
1190.IP "" 2
1191Local directory only, no recursion.
1192.SP
1193.IP "" 0
1194\fB-R\fR
1195.IP "" 2
1196Process directories recursively.
1197.SP
1198.IP "" 0
1199\fB-f\fR
1200.IP "" 2
1201Use head revision if tag/date not found.
1202.SP
1203.IP "" 0
1204\fB-F\fR
1205.IP "" 2
1206Annotate binary files.
1207.SP
1208.IP "" 0
1209\fB-r \fIrevision\fB\fR
1210.IP "" 2
1211Annotate file as of specified revision/tag.
1212.SP
1213.IP "" 0
1214\fB-D \fIdate\fB\fR
1215.IP "" 2
1216Annotate file as of specified date.
1217.SP
1218.SH "annotate example"
1219.SP
1220For example:
1221.SP
1222.PD 0
1223.SP
1224.IP "" 2
1225$ cvs annotate ssfile
1226.IP "" 2
1227Annotations for ssfile
1228.IP "" 2
1229***************
1230.IP "" 2
12311.1          (mary     27-Mar-96): ssfile line 1
1232.IP "" 2
12331.2          (joe      28-Mar-96): ssfile line 2
1234
1235.PD
1236.IP "" 0
1237.SP
1238The file \fBssfile\fR currently contains two lines.
1239The \fBssfile line 1\fR line was checked in by
1240\fBmary\fR on March 27.  Then, on March 28, \fBjoe\fR
1241added a line \fBssfile line 2\fR, without modifying
1242the \fBssfile line 1\fR line.  This report doesn\(aqt
1243tell you anything about lines which have been deleted
1244or replaced; you need to use \fBcvs diff\fR for that
1245(see node `diff\(aq in the CVS manual).
1246.SP
1247The options to \fBcvs annotate\fR are listed in
1248`Invoking CVS\(aq in the CVS manual, and can be used to select the files
1249and revisions to annotate.  The options are described
1250in more detail there and in `Common options\(aq in the CVS manual.
1251.SP
1252.SH "checkout"
1253.SS "Check out sources for editing"
1254.IX "checkout (subcommand)"
1255.IX "co (subcommand)"
1256.SP
1257.IP "\(bu" 2
1258Synopsis: checkout [options] modules\&...
1259.IP "\(bu" 2
1260Requires: repository.
1261.IP "\(bu" 2
1262Changes: working directory.
1263.IP "\(bu" 2
1264Synonyms: co, get
1265.SP
1266Create or update a working directory containing copies of the
1267source files specified by \fImodules\fR.  You must execute
1268\fBcheckout\fR before using most of the other \fBcvs\fR
1269commands, since most of them operate on your working
1270directory.
1271.SP
1272The \fImodules\fR are either
1273symbolic names for some
1274collection of source directories and files, or paths to
1275directories or files in the repository.  The symbolic
1276names are defined in the \fBmodules\fR file.
1277See `modules\(aq in the CVS manual.
1278.SP
1279Depending on the modules you specify, \fBcheckout\fR may
1280recursively create directories and populate them with
1281the appropriate source files.  You can then edit these
1282source files at any time (regardless of whether other
1283software developers are editing their own copies of the
1284sources); update them to include new changes applied by
1285others to the source repository; or commit your work as
1286a permanent change to the source repository.
1287.SP
1288Note that \fBcheckout\fR is used to create
1289directories.  The top-level directory created is always
1290added to the directory where \fBcheckout\fR is
1291invoked, and usually has the same name as the specified
1292module.  In the case of a module alias, the created
1293sub-directory may have a different name, but you can be
1294sure that it will be a sub-directory, and that
1295\fBcheckout\fR will show the relative path leading to
1296each file as it is extracted into your private work
1297area (unless you specify the \fB-Q\fR global option).
1298.SP
1299The files created by \fBcheckout\fR are created
1300read-write, unless the \fB-r\fR option to \fBcvs\fR
1301(see node `Global options\(aq in the CVS manual) is specified, the
1302\fBCVSREAD\fR environment variable is specified
1303(see node `Environment variables\(aq in the CVS manual), or a watch is in
1304effect for that file (see node `Watches\(aq in the CVS manual).
1305.SP
1306Note that running \fBcheckout\fR on a directory that was already
1307built by a prior \fBcheckout\fR is also permitted.
1308This is similar to specifying the \fB-d\fR option
1309to the \fBupdate\fR command in the sense that new
1310directories that have been created in the repository
1311will appear in your work area.
1312However, \fBcheckout\fR takes a module name whereas
1313\fBupdate\fR takes a directory name.  Also
1314to use \fBcheckout\fR this way it must be run from the
1315top level directory (where you originally ran
1316\fBcheckout\fR from), so before you run
1317\fBcheckout\fR to update an existing directory, don\(aqt
1318forget to change your directory to the top level
1319directory.
1320.SP
1321For the output produced by the \fBcheckout\fR command,
1322see node `update output\(aq in the CVS manual.
1323.SP
1324.SH "checkout options"
1325.SP
1326These standard options are supported by \fBcheckout\fR
1327(see node `Common options\(aq in the CVS manual for a complete description of
1328them):
1329.SP
1330.IP "" 0
1331\fB-D \fIdate\fB\fR
1332.IP "" 2
1333Use the most recent revision no later than \fIdate\fR.
1334This option is sticky, and implies \fB-P\fR.  See
1335`Sticky tags\(aq in the CVS manual for more information on sticky tags/dates.
1336.SP
1337.IP "" 0
1338\fB-f\fR
1339.IP "" 2
1340Only useful with the \fB-D \fIdate\fB\fR or \fB-r
1341\fItag\fB\fR flags.  If no matching revision is found,
1342retrieve the most recent revision (instead of ignoring
1343the file).
1344.SP
1345.IP "" 0
1346\fB-k \fIkflag\fB\fR
1347.IP "" 2
1348Process keywords according to \fIkflag\fR.  See
1349`Keyword substitution\(aq in the CVS manual.
1350This option is sticky; future updates of
1351this file in this working directory will use the same
1352\fIkflag\fR.  The \fBstatus\fR command can be viewed
1353to see the sticky options.  See `Invoking CVS\(aq in the CVS manual for
1354more information on the \fBstatus\fR command.
1355.SP
1356.IP "" 0
1357\fB-l\fR
1358.IP "" 2
1359Local; run only in current working directory.
1360.SP
1361.IP "" 0
1362\fB-n\fR
1363.IP "" 2
1364Do not run any checkout program (as specified
1365with the \fB-o\fR option in the modules file;
1366see node `modules\(aq in the CVS manual).
1367.SP
1368.IP "" 0
1369\fB-P\fR
1370.IP "" 2
1371Prune empty directories.  See `Moving directories\(aq in the CVS manual.
1372.SP
1373.IP "" 0
1374\fB-p\fR
1375.IP "" 2
1376Pipe files to the standard output.
1377.SP
1378.IP "" 0
1379\fB-R\fR
1380.IP "" 2
1381Checkout directories recursively.  This option is on by default.
1382.SP
1383.IP "" 0
1384\fB-r \fItag\fB\fR
1385.IP "" 2
1386Use revision \fItag\fR.  This option is sticky, and implies \fB-P\fR.
1387See `Sticky tags\(aq in the CVS manual, for more information on sticky tags/dates.
1388.SP
1389In addition to those, you can use these special command
1390options with \fBcheckout\fR:
1391.SP
1392.IP "" 0
1393\fB-A\fR
1394.IP "" 2
1395Reset any sticky tags, dates, or \fB-k\fR options.
1396Does not reset sticky \fB-k\fR options on modified files.
1397See `Sticky tags\(aq in the CVS manual for more information on sticky tags/dates.
1398.SP
1399.IP "" 0
1400\fB-c\fR
1401.IP "" 2
1402Copy the module file, sorted, to the standard output,
1403instead of creating or modifying any files or
1404directories in your working directory.
1405.SP
1406.IP "" 0
1407\fB-d \fIdir\fB\fR
1408.IP "" 2
1409Create a directory called \fIdir\fR for the working
1410files, instead of using the module name.  In general,
1411using this flag is equivalent to using \fBmkdir
1412\fIdir\fB; cd \fIdir\fB\fR followed by the checkout
1413command without the \fB-d\fR flag.
1414.SP
1415There is an important exception, however.  It is very
1416convenient when checking out a single item to have the
1417output appear in a directory that doesn\(aqt contain empty
1418intermediate directories.  In this case \fIonly\fR,
1419\fBcvs\fR tries to \`\`shorten\(aq\(aq pathnames to avoid those empty
1420directories.
1421.SP
1422For example, given a module \fBfoo\fR that contains
1423the file \fBbar.c\fR, the command \fBcvs co -d dir
1424foo\fR will create directory \fBdir\fR and place
1425\fBbar.c\fR inside.  Similarly, given a module
1426\fBbar\fR which has subdirectory \fBbaz\fR wherein
1427there is a file \fBquux.c\fR, the command \fBcvs co
1428-d dir bar/baz\fR will create directory \fBdir\fR and
1429place \fBquux.c\fR inside.
1430.SP
1431Using the \fB-N\fR flag will defeat this behavior.
1432Given the same module definitions above, \fBcvs co
1433-N -d dir foo\fR will create directories \fBdir/foo\fR
1434and place \fBbar.c\fR inside, while \fBcvs co -N -d
1435dir bar/baz\fR will create directories \fBdir/bar/baz\fR
1436and place \fBquux.c\fR inside.
1437.SP
1438.IP "" 0
1439\fB-j \fItag\fB\fR
1440.IP "" 2
1441With two \fB-j\fR options, merge changes from the
1442revision specified with the first \fB-j\fR option to
1443the revision specified with the second \fBj\fR option,
1444into the working directory.
1445.SP
1446With one \fB-j\fR option, merge changes from the
1447ancestor revision to the revision specified with the
1448\fB-j\fR option, into the working directory.  The
1449ancestor revision is the common ancestor of the
1450revision which the working directory is based on, and
1451the revision specified in the \fB-j\fR option.
1452.SP
1453In addition, each -j option can contain an optional
1454date specification which, when used with branches, can
1455limit the chosen revision to one within a specific
1456date.  An optional date is specified by adding a colon
1457(:) to the tag:
1458\fB-j\fISymbolic_Tag\fB:\fIDate_Specifier\fB\fR.
1459.SP
1460See `Branching and merging\(aq in the CVS manual.
1461.SP
1462.IP "" 0
1463\fB-N\fR
1464.IP "" 2
1465Only useful together with \fB-d \fIdir\fB\fR.  With
1466this option, \fBcvs\fR will not \`\`shorten\(aq\(aq module paths
1467in your working directory when you check out a single
1468module.  See the \fB-d\fR flag for examples and a
1469discussion.
1470.SP
1471.IP "" 0
1472\fB-s\fR
1473.IP "" 2
1474Like \fB-c\fR, but include the status of all modules,
1475and sort it by the status string.  See `modules\(aq in the CVS manual, for
1476info about the \fB-s\fR option that is used inside the
1477modules file to set the module status.
1478.SP
1479.SH "checkout examples"
1480.SP
1481Get a copy of the module \fBtc\fR:
1482.SP
1483.PD 0
1484.SP
1485.IP "" 2
1486$ cvs checkout tc
1487
1488.PD
1489.IP "" 0
1490.SP
1491Get a copy of the module \fBtc\fR as it looked one day
1492ago:
1493.SP
1494.PD 0
1495.SP
1496.IP "" 2
1497$ cvs checkout -D yesterday tc
1498
1499.PD
1500.IP "" 0
1501.SP
1502.SH "commit"
1503.SS "Check files into the repository"
1504.IX "commit (subcommand)"
1505.SP
1506.IP "\(bu" 2
1507Synopsis: commit [-lRf] [-m \(aqlog_message\(aq |
1508-F file] [-r revision] [files\&...]
1509.IP "\(bu" 2
1510Requires: working directory, repository.
1511.IP "\(bu" 2
1512Changes: repository.
1513.IP "\(bu" 2
1514Synonym: ci
1515.SP
1516Use \fBcommit\fR when you want to incorporate changes
1517from your working source files into the source
1518repository.
1519.SP
1520If you don\(aqt specify particular files to commit, all of
1521the files in your working current directory are
1522examined.  \fBcommit\fR is careful to change in the
1523repository only those files that you have really
1524changed.  By default (or if you explicitly specify the
1525\fB-R\fR option), files in subdirectories are also
1526examined and committed if they have changed; you can
1527use the \fB-l\fR option to limit \fBcommit\fR to the
1528current directory only.
1529.SP
1530\fBcommit\fR verifies that the selected files are up
1531to date with the current revisions in the source
1532repository; it will notify you, and exit without
1533committing, if any of the specified files must be made
1534current first with \fBupdate\fR (see node `update\(aq in the CVS manual).
1535\fBcommit\fR does not call the \fBupdate\fR command
1536for you, but rather leaves that for you to do when the
1537time is right.
1538.SP
1539When all is well, an editor is invoked to allow you to
1540enter a log message that will be written to one or more
1541logging programs (see node `modules\(aq in the CVS manual, and see node `loginfo\(aq in the CVS manual)
1542and placed in the \fBrcs\fR file inside the
1543repository.  This log message can be retrieved with the
1544\fBlog\fR command; see node `log\(aq in the CVS manual.  You can specify the
1545log message on the command line with the \fB-m
1546\fImessage\fB\fR option, and thus avoid the editor invocation,
1547or use the \fB-F \fIfile\fB\fR option to specify
1548that the argument file contains the log message.
1549.SP
1550.SH "commit options"
1551.SP
1552These standard options are supported by \fBcommit\fR
1553(see node `Common options\(aq in the CVS manual for a complete description of
1554them):
1555.SP
1556.IP "" 0
1557\fB-l\fR
1558.IP "" 2
1559Local; run only in current working directory.
1560.SP
1561.IP "" 0
1562\fB-R\fR
1563.IP "" 2
1564Commit directories recursively.  This is on by default.
1565.SP
1566.IP "" 0
1567\fB-r \fIrevision\fB\fR
1568.IP "" 2
1569Commit to \fIrevision\fR.  \fIrevision\fR must be
1570either a branch, or a revision on the main trunk that
1571is higher than any existing revision number
1572(see node `Assigning revisions\(aq in the CVS manual).  You
1573cannot commit to a specific revision on a branch.
1574.SP
1575\fBcommit\fR also supports these options:
1576.SP
1577.IP "" 0
1578\fB-F \fIfile\fB\fR
1579.IP "" 2
1580Read the log message from \fIfile\fR, instead
1581of invoking an editor.
1582.SP
1583.IP "" 0
1584\fB-f\fR
1585.IP "" 2
1586Note that this is not the standard behavior of
1587the \fB-f\fR option as defined in `Common options\(aq in the CVS manual.
1588.SP
1589Force \fBcvs\fR to commit a new revision even if you haven\(aqt
1590made any changes to the file.  If the current revision
1591of \fIfile\fR is 1.7, then the following two commands
1592are equivalent:
1593.SP
1594.PD 0
1595.SP
1596.IP "" 4
1597$ cvs commit -f \fIfile\fR
1598.IP "" 4
1599$ cvs commit -r 1.8 \fIfile\fR
1600
1601.PD…

Large files files are truncated, but you can click here to view the full file