Annotation of src/usr.bin/rcs/rcsfile.5, Revision 1.1
1.1 ! schwarze 1: .\" $OpenBSD$
! 2: .\"
! 3: .\" Copyright (c) 2019 Fabio Scotoni <fabio@esse.ch>
! 4: .\"
! 5: .\" Permission to use, copy, modify, and distribute this software for any
! 6: .\" purpose with or without fee is hereby granted, provided that the above
! 7: .\" copyright notice and this permission notice appear in all copies.
! 8: .\"
! 9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
! 10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
! 12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
! 15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 16: .\"
! 17: .Dd $Mdocdate$
! 18: .Dt RCSFILE 5
! 19: .Os
! 20: .Sh NAME
! 21: .Nm rcsfile
! 22: .Nd format of an RCS file
! 23: .Sh DESCRIPTION
! 24: An RCS file is a text file.
! 25: It consists of four sections, each separated by two empty lines.
! 26: RCS files should not be edited by hand;
! 27: the
! 28: .Xr rcs 1
! 29: programs should be used instead.
! 30: .Ss Administrative data
! 31: The RCS file begins with admin data.
! 32: Each entry in this section consists of either one or multiple values.
! 33: Entries that take one value are specified on one line:
! 34: The keyword and its corresponding value are separated by
! 35: a tab character.
! 36: Entries that take multiple values begin with a keyword on one line;
! 37: the values are specified on subsequent lines, one per line and
! 38: prefixed with a tab character.
! 39: If the list is empty, the semicolon immediately follows the keyword.
! 40: Entries are terminated with a semicolon.
! 41: The entries are:
! 42: .Bl -tag -width Ds
! 43: .It Ic head Ar rev
! 44: Highest revision number.
! 45: .It Ic branch Ar rev
! 46: Revision number that specifies the default branch (optional).
! 47: .It Ic access
! 48: List of users that are allowed to check in new revisions with
! 49: .Xr ci 1 .
! 50: This keyword is not followed by a tab;
! 51: instead, the list of users is specified with one username per line.
! 52: The list is terminated by a single semicolon.
! 53: .It Ic symbols
! 54: List of symbolic names used as aliases for specific revisions.
! 55: Each entry consists of a symbolic name followed by a colon and
! 56: the revision.
! 57: .It Ic locks
! 58: List of locked revisions.
! 59: Each entry consists of a username followed by a colon and
! 60: the locked revision.
! 61: .It Ic strict
! 62: Indicates that locks are strict;
! 63: if missing, locks are not strict.
! 64: This entry takes no value and immediately follows the list of locks
! 65: without a newline.
! 66: .It Ic comment Pf @ Ar leader Ns @
! 67: Contains the comment leader surrounded by at signs.
! 68: .It Ic expand Pf @ Ar mode Ns @
! 69: Indicates the keyword substitution mode.
! 70: See
! 71: .Xr rcs 1
! 72: for the possible keyword substitution modes.
! 73: If this entry is not given in the admin section,
! 74: .Ar kv
! 75: must be assumed.
! 76: .El
! 77: .Ss List of deltas
! 78: The RCS file continues with a list of deltas.
! 79: Deltas are separated by empty lines.
! 80: The list begins with the head and ends with the initial revision.
! 81: Each entry begins with the revision number, followed by a newline.
! 82: After that, the structure follows the admin section.
! 83: .Bl -tag -width Ds
! 84: .It Ic date Ar YYYY . Ns Ar mm . Ns Ar dd . Ns Ar HH . Ns Ar MM . Ns Ar SS
! 85: Indicates the date and UTC time the revision was checked in.
! 86: The date consists of the year, the month,
! 87: the day of month, the hour, the minute and the second,
! 88: each separated by dots.
! 89: The year is specified in either two or four digits.
! 90: The other values are specified in two digits each.
! 91: .It Ic author Ar username
! 92: Author's username.
! 93: This entry immediately follows the
! 94: .Ic date
! 95: without a newline.
! 96: .It Ic state Ar value
! 97: Contains the state of this delta,
! 98: which is an arbitrary string.
! 99: This entry immediately follows the
! 100: .Ic author
! 101: without a newline.
! 102: .It Ic branches
! 103: List of revision numbers that are branches stemming from this delta.
! 104: .It Ic next Ar rev
! 105: Next revision.
! 106: Chronologically, this is the
! 107: .Em previous
! 108: revision.
! 109: For the initial check-in,
! 110: .Ar rev
! 111: is empty,
! 112: but the tab character that acts as separator is nonetheless present.
! 113: .El
! 114: .Ss Description
! 115: The RCS file continues with the description.
! 116: It consists of the string
! 117: .Ic desc
! 118: followed by a newline and then an at sign.
! 119: The description is an arbitrary string that can span multiple lines.
! 120: A single at sign on a line terminates the description.
! 121: At signs anywhere in the description itself
! 122: are escaped by prefixing them with another at sign.
! 123: .Ss List of deltatexts
! 124: Finally, the RCS file contains the deltatexts.
! 125: The list of deltatexts is ordered the same as the list of deltas.
! 126: Deltatexts are separated by two lines.
! 127: Each entry begins with the revision number, followed by a newline.
! 128: The text
! 129: .Dq Ic log
! 130: follows on its own line.
! 131: The log message follows on another new line;
! 132: it consists of an at sign, the log message itself (which may span
! 133: multiple lines), and finally an at sign on its own line.
! 134: Then the text
! 135: .Dq Ic text
! 136: follows on its own line.
! 137: The format is the same as for the description and log message.
! 138: As with the description,
! 139: at signs anywhere in the log message or in the deltatext itself
! 140: are escaped by prefixing them with another at sign.
! 141: The deltatext of the head consists of the full file contents.
! 142: All subsequent deltatexts contain the differences to the previous
! 143: deltatext in the format of
! 144: .Xr diff 1
! 145: .Fl n .
! 146: .Sh SEE ALSO
! 147: .Xr ci 1 ,
! 148: .Xr co 1 ,
! 149: .Xr cvs 1 ,
! 150: .Xr ident 1 ,
! 151: .Xr rcs 1 ,
! 152: .Xr rcsclean 1 ,
! 153: .Xr rcsdiff 1 ,
! 154: .Xr rcsmerge 1