Annotation of src/usr.bin/cvs/cvs.5, Revision 1.1
1.1 ! jmc 1: .\" $OpenBSD$
! 2: .\"
! 3: .\" Copyright (c) 2004 Jean-Francois Brousseau <jfb@openbsd.org>
! 4: .\" Copyright (c) 2004-2007 Xavier Santolaria <xsa@openbsd.org>
! 5: .\" All rights reserved.
! 6: .\"
! 7: .\" Redistribution and use in source and binary forms, with or without
! 8: .\" modification, are permitted provided that the following conditions
! 9: .\" are met:
! 10: .\"
! 11: .\" 1. Redistributions of source code must retain the above copyright
! 12: .\" notice, this list of conditions and the following disclaimer.
! 13: .\" 2. The name of the author may not be used to endorse or promote products
! 14: .\" derived from this software without specific prior written permission.
! 15: .\"
! 16: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
! 17: .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
! 18: .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
! 19: .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
! 20: .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
! 21: .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
! 22: .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
! 23: .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
! 24: .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
! 25: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
! 26: .\"
! 27: .Dd April 13, 2007
! 28: .Dt CVS 5
! 29: .Os
! 30: .Sh NAME
! 31: .Nm cvs
! 32: .Nd OpenCVS files format
! 33: .Sh DESCRIPTION
! 34: This manual page documents the various support files for
! 35: .Xr cvs 1
! 36: and the format of those files.
! 37: .Pp
! 38: The location of a module's files are known as its
! 39: .Dv CVSROOT .
! 40: The files within CVSROOT are as follows:
! 41: .Bl -tag -width Ds
! 42: .It Pa $CVSROOT/CVSROOT
! 43: Directory containing repository administrative files.
! 44: .It Pa $CVSROOT/CVSROOT/config
! 45: File containing various configuration options.
! 46: The format of each line is as follows:
! 47: .Pp
! 48: .Dl keyword=value
! 49: .Pp
! 50: Extraneous spaces or tabs are not permitted.
! 51: A line beginning with a hash character
! 52: .Pq Sq #
! 53: is considered a comment and ignored.
! 54: .Pp
! 55: The following options are available:
! 56: .Pp
! 57: .Bl -tag -width "dlimit=XvalueXXX" -offset indent -compact
! 58: .It dlimit='value'
! 59: Set the process data size limit.
! 60: .It tag='value'
! 61: Set the name of a local tag to use in addition to Id.
! 62: .It umask='value'
! 63: Set the default umask to use when creating files and directories.
! 64: .El
! 65: .It Pa $CVSROOT/CVSROOT/history
! 66: File containing reports of
! 67: .Ic checkout ,
! 68: .Ic commit ,
! 69: .Ic export ,
! 70: .Ic release ,
! 71: .Ic rtag ,
! 72: and
! 73: .Ic update
! 74: commands that have been issued.
! 75: By default, the
! 76: .Ic init
! 77: command creates the
! 78: .Pa history
! 79: file.
! 80: To disable history logging, the
! 81: .Pa history
! 82: file should be removed manually.
! 83: The
! 84: .Ic history
! 85: command shows these reports according to several criteria.
! 86: .It Pa $CVSROOT/CVSROOT/loginfo
! 87: File containing associations between modules and handlers for
! 88: post-commit logging.
! 89: .El
! 90: .Pp
! 91: Each directory that is managed by
! 92: .Nm
! 93: contains a
! 94: .Pa CVS
! 95: directory.
! 96: This directory is used by various
! 97: .Nm
! 98: commands to record the status of files in the current working directory.
! 99: These files should not be modified manually by the user but by the
! 100: .Nm
! 101: commands instead.
! 102: Files that are always stored in every
! 103: .Pa CVS
! 104: directory are as follows:
! 105: .Bl -tag -width Ds
! 106: .It Pa CVS/Entries
! 107: File containing a list of files managed by
! 108: .Nm .
! 109: .Pa Entries
! 110: has one line per file or directory describing the state of it with
! 111: regard to the source repository.
! 112: These lines have the following format:
! 113: .Pp
! 114: .Dl /name/revision/timestamp/options/tag
! 115: .Bl -tag -width Ds
! 116: .It name
! 117: Name of the file in the directory.
! 118: .It revision
! 119: Revision of the file in the working directory.
! 120: The revision is equal to
! 121: .Sq 0
! 122: if the file has been added with the
! 123: .Ic add
! 124: command or preceded by the
! 125: .Sq -
! 126: character if the file has been removed with the
! 127: .Ic remove
! 128: command.
! 129: .It timestamp
! 130: Contains the timestamp of the file at the time
! 131: .Nm
! 132: created it.
! 133: If the timestamp is different from the actual modification time of the file,
! 134: it means that the file has been modified.
! 135: .It options
! 136: Contains the keyword substitution mode used for this file.
! 137: .It tag
! 138: Contains
! 139: .Sq T
! 140: followed by a tagname or
! 141: .Sq D
! 142: followed by a date.
! 143: .El
! 144: .Pp
! 145: Entries corresponding to directories have the following format:
! 146: .Pp
! 147: .Dl D/name////
! 148: .Pp
! 149: The lines in the
! 150: .Pa Entries
! 151: file can be in any order.
! 152: .It Pa CVS/Repository
! 153: File containing the path to the corresponding directory in the
! 154: source repository.
! 155: .It Pa CVS/Root
! 156: File containing the value of the
! 157: .Ev CVSROOT
! 158: variable at the time of checkout.
! 159: This file is used by all
! 160: .Nm
! 161: commands instead of
! 162: .Ev CVSROOT
! 163: once
! 164: .Nm
! 165: has checked for its existence.
! 166: .El
! 167: .Pp
! 168: Depending on the circumstances, other files may exist in the
! 169: .Pa CVS
! 170: directory:
! 171: .Bl -tag -width Ds
! 172: .It Pa CVS/Base
! 173: If pseudo-lock mode is enabled in client-server mode,
! 174: the
! 175: .Pa Base
! 176: directory contains a copy of the file on which the
! 177: .Ic edit
! 178: command has been issued.
! 179: This allows the
! 180: .Ic unedit
! 181: command to operate even if the CVS server is unreachable.
! 182: .It Pa CVS/Baserev
! 183: File listing the revisions for each file contained in the
! 184: .Pa Base
! 185: directory under the following format:
! 186: .Pp
! 187: .Dl name/revision/
! 188: .It Pa CVS/Baserev.tmp
! 189: Temporary file used to write
! 190: .Pa CVS/Baserev
! 191: content then atomically renamed to
! 192: .Pa Baserev .
! 193: .It Pa CVS/Checkin.prog
! 194: File containing the path to the command specified with the
! 195: .Fl i
! 196: option in the
! 197: .Pa CVSROOT/modules
! 198: file.
! 199: .It Pa CVS/Entries.Backup
! 200: Temporary file used to write
! 201: .Pa CVS/Entries
! 202: content then atomically renamed to
! 203: .Pa Entries .
! 204: .It Pa CVS/Entries.Static
! 205: Tells
! 206: .Nm
! 207: to not add files to the directory unless the
! 208: .Ic update
! 209: command is issued with the
! 210: .Fl d
! 211: option.
! 212: .It Pa CVS/Notify
! 213: File containing the notifications that could not be sent to the
! 214: CVS server but will be sent at the next successful connection.
! 215: .It Pa CVS/Notify.tmp
! 216: Temporary file used to write
! 217: .Pa CVS/Notify
! 218: content then atomically renamed to
! 219: .Pa Notify .
! 220: .It Pa CVS/Tag
! 221: File containing the symbolic revision that was used at checkout.
! 222: The first character of the line is a single letter indicating the
! 223: type of tag:
! 224: .Sq D ,
! 225: .Sq N ,
! 226: or
! 227: .Sq T ,
! 228: for date, non-branch tag, or branch tag, respectively.
! 229: The rest of the line is the tag or date itself.
! 230: The
! 231: .Pa Tag
! 232: file should not be removed manually:
! 233: instead, use
! 234: .Dq update -A .
! 235: .It Pa CVS/Template
! 236: File containing the template specified by the
! 237: .Pa CVSROOT/rcsinfo
! 238: file.
! 239: It is only used in client-server mode.
! 240: Locally,
! 241: .Nm
! 242: uses the
! 243: .Pa rcsinfo
! 244: file directly.
! 245: .It Pa CVS/Update.prog
! 246: File containing the path to the command specified with the
! 247: .Fl u
! 248: option in the
! 249: .Pa CVSROOT/modules
! 250: file.
! 251: .It Pa CVS/<name>,t
! 252: File containing the description of the file
! 253: .Pa file
! 254: that has been added with the
! 255: .Ic add
! 256: command.
! 257: This description is used by
! 258: .Nm
! 259: when archiving this file with the
! 260: .Ic commit
! 261: command.
! 262: .It Pa $HOME/.cvsignore
! 263: This file provides a list of files (or
! 264: .Xr sh 1
! 265: file name patterns) that should be ignored by
! 266: .Xr cvs 1
! 267: during the
! 268: .Ic import ,
! 269: .Ic release ,
! 270: and
! 271: .Ic update
! 272: commands.
! 273: .Pp
! 274: The syntax of the
! 275: .Nm
! 276: file consists of a series of lines, each of which contains a
! 277: space-separated list of filenames.
! 278: There is currently no way of using comments in this file.
! 279: .Pp
! 280: Default patterns that are ignored by
! 281: .Xr cvs 1
! 282: are as follows:
! 283: .Bd -filled
! 284: CVS,
! 285: RCS,
! 286: RCSLOG,
! 287: SCCS,
! 288: TAGS,
! 289: tags,
! 290: core,
! 291: cvslog*,
! 292: *.o,
! 293: *.so,
! 294: *.a,
! 295: *.bak,
! 296: *.orig,
! 297: *.rej,
! 298: *.old,
! 299: *.exe,
! 300: *.depend,
! 301: *.obj,
! 302: *.elc,
! 303: *.ln,
! 304: *.olb,
! 305: *.core,
! 306: .#*,
! 307: *~,
! 308: _$*,
! 309: *$,
! 310: #*,
! 311: ,*.
! 312: .Ed
! 313: .Pp
! 314: The list can be modified using the methods described below:
! 315: .Pp
! 316: .Bl -enum -compact
! 317: .It
! 318: The
! 319: .Pa $CVSROOT/CVSROOT/cvsignore
! 320: file appends patterns to ignore for the whole repository.
! 321: .It
! 322: The
! 323: .Pa $HOME/.cvsignore
! 324: file appends patterns to ignore for user only.
! 325: .It
! 326: The content of the
! 327: .Ev CVSIGNORE
! 328: variable is appended to the list.
! 329: .It
! 330: Options to the command line
! 331: .Fl I
! 332: flag, available for the
! 333: .Ic import
! 334: and
! 335: .Ic update
! 336: commands, appends patterns for the current command line action only.
! 337: .It
! 338: .Pa .cvsignore
! 339: files placed in the repository directories allow to add patterns to
! 340: ignore locally.
! 341: They do not take effect on sub-directories.
! 342: .El
! 343: .Pp
! 344: The
! 345: .Sq !\&
! 346: character can be used to reset the list of patterns using any of these
! 347: five methods.
! 348: .Pp
! 349: For the
! 350: .Ic update
! 351: command,
! 352: .Xr cvs 1
! 353: handles files that are already present in the repository even if they
! 354: are in the list to ignore.
! 355: Files that are in the list to ignore but not in the repository will not
! 356: be listed.
! 357: This way, files preceded by the
! 358: .Sq ?\&
! 359: character will not appear even if they should.
! 360: .It Pa $HOME/.cvsrc
! 361: This file provides a way to give the
! 362: .Xr cvs 1
! 363: program implicit global options and command-specific options.
! 364: Unless the
! 365: .Fl f
! 366: option is specified,
! 367: .Xr cvs 1
! 368: reads its startup configuration file
! 369: .Pa .cvsrc
! 370: from the home directory of the user who invoked it.
! 371: .Pp
! 372: The format of each line is as follows:
! 373: .Pp
! 374: .Dl command [arg ...]
! 375: .Pp
! 376: where
! 377: .Ar command
! 378: is either the
! 379: .Sq cvs
! 380: keyword to specify global options, one of the supported
! 381: .Xr cvs 1
! 382: commands or a command alias.
! 383: Arguments following
! 384: .Ar command
! 385: will be added implicitly to the appropriate command's argument vector if it is
! 386: run.
! 387: Lines whose
! 388: .Ar command
! 389: argument is not a valid command will generate a warning when running without
! 390: the
! 391: .Fl q
! 392: or
! 393: .Fl Q
! 394: flags.
! 395: .Pp
! 396: Empty lines and lines specifying no optional arguments are ignored.
! 397: A line beginning with a hash character
! 398: .Pq Sq #
! 399: is considered a comment and ignored.
! 400: .Pp
! 401: For example, to specify that
! 402: .Xr cvs 1
! 403: should always run in quiet mode and the
! 404: .Ic diff
! 405: internal command should always produce unified output:
! 406: .Bd -literal -offset indent
! 407: cvs -q
! 408: diff -u
! 409: .Ed
! 410: .It Pa $HOME/.cvswrappers
! 411: This file, located in
! 412: .Pa $CVSROOT/CVSROOT
! 413: and/or
! 414: .Pa $HOME/.cvswrappers ,
! 415: provides a way to configure filters for
! 416: .Xr cvs 1
! 417: based on file type (name).
! 418: This works by specifying a pattern to match for varying file types.
! 419: .Pp
! 420: The format of each line is as follows:
! 421: .Pp
! 422: .Dl pattern [option 'value'] [option 'value'] ...
! 423: .Pp
! 424: The following options are supported:
! 425: .Bl -tag -width Ds
! 426: .It Fl f Ar filter
! 427: Execute
! 428: .Ar filter
! 429: when the file is extracted from the repository (for the
! 430: .Ic checkout ,
! 431: .Ic export ,
! 432: and
! 433: .Ic update
! 434: commands).
! 435: .It Fl k Ar mode
! 436: Specify the keyword substitution mode.
! 437: See the
! 438: .Sx KEYWORD SUBSTITUTION
! 439: section of
! 440: .Xr rcs 1
! 441: for more information.
! 442: .It Fl m Ar method
! 443: Specify the merge methodology to be used when a file is updated.
! 444: .Pp
! 445: The methods are as follows:
! 446: .Bl -tag -width Ds
! 447: .It COPY
! 448: When the
! 449: .Ic update
! 450: command is used,
! 451: .Xr cvs 1
! 452: will merely copy one version over another and let the user do the merge
! 453: by himself.
! 454: This method is used by default on binary files (see the
! 455: .Fl k Ar b
! 456: option).
! 457: .It MERGE
! 458: Try to merge the files.
! 459: This method is the default.
! 460: .El
! 461: .It Fl t Ar filter
! 462: Execute
! 463: .Ar filter
! 464: before the file is archived in the repository (for the
! 465: .Ic commit ,
! 466: and
! 467: .Ic import
! 468: commands).
! 469: .El
! 470: .It Pa $TMPDIR/cvs-serv Ns Aq Pa pid
! 471: Temporary directory created by the server where
! 472: .Ar pid
! 473: is the process ID of the server.
! 474: It is located in the directory specified by the
! 475: .Ev TMPDIR
! 476: environment variable or the
! 477: .Fl T
! 478: global option.
! 479: See above for more information.
! 480: .El
! 481: .Sh SEE ALSO
! 482: .Xr cvs 1 ,
! 483: .Xr cvsintro 7