contrib/cvs/doc/RCSFILES

   1 It would be nice if the RCS file format (which is implemented by a
   2 great many tools, both free and non-free, both by calling GNU RCS and
   3 by reimplementing access to RCS files) were documented in some
   4 standard separate from any one tool.  But as far as I know no such
   5 standard exists.  Hence this file.
   6
   7 The place to start is the rcsfile.5 manpage in the GNU RCS 5.7
   8 distribution.  Then look at the diff at the end of this file (which
   9 contains a few fixes and clarifications to that manpage).
  10
  11 If you are interested in MKS RCS, src/ci.c in GNU RCS 5.7 has a
  12 comment about their date format.  However, as far as we know there
  13 isn't really any document describing MKS's changes to the RCS file
  14 format.
  15
  16 The rcsfile.5 manpage does not document what goes in the "text" field
  17 for each revision.  The answer is that the head revision contains the
  18 contents of that revision and every other revision contain a bunch of
  19 edits to produce that revision ("a" and "d" lines).  The GNU diff
  20 manual (the version I looked at was for GNU diff 2.4) documents this
  21 format somewhat (as the "RCS output format"), but the presentation is
  22 a bit confusing as it is all tangled up with the documentation of
  23 several other output formats.  If you just want some source code to
  24 look at, the part of CVS which applies these is RCS_deltas in
  25 src/rcs.c.
  26
  27 The rcsfile.5 documentation only _very_ briefly touches on the order
  28 of the revisions.  The order _is_ important and CVS relies on it.
  29 Here is an example of what I was able to find, based on the join3
  30 sanity.sh testcase (and the behavior I am documenting here seems to be
  31 the same for RCS 5.7 and CVS 1.9.27):
  32
  33     1.1 ----------------->  1.2
  34      \---> 1.1.2.1           \---> 1.2.2.1
  35
  36 Here is how this shows up in the RCS file (omitting irrelevant parts):
  37
  38   admin:  head 1.2;
  39   deltas:
  40     1.2 branches 1.2.2.1; next 1.1;
  41     1.1 branches 1.1.2.1; next;
  42     1.1.2.1 branches; next;
  43     1.2.2.1 branches; next;
  44   deltatexts:
  45     1.2
  46     1.2.2.1
  47     1.1
  48     1.1.2.1
  49
  50 Yes, the order seems to differ between the deltas and the deltatexts.
  51 I have no idea how much of this should actually be considered part of
  52 the RCS file format, and how much programs reading it should expect to
  53 encounter any order.
  54
  55 The rcsfile.5 grammar shows the {num} after "next" as optional; if it
  56 is omitted then there is no next delta node (for example 1.1 or the
  57 head of a branch will typically have no next).
  58
  59 There is one case where CVS uses CVS-specific, non-compatible changes
  60 to the RCS file format, and this is magic branches.  See cvs.texinfo
  61 for more information on them.  CVS also sets the RCS state to "dead"
  62 to indicate that a file does not exist in a given revision (this is
  63 stored just as any other RCS state is).
  64
  65 The RCS file format allows quite a variety of extensions to be added
  66 in a compatible manner by use of the "newphrase" feature documented in
  67 rcsfile.5.  We won't try to document extensions not used by CVS in any
  68 detail, but we will briefly list them.  Each occurrence of a newphrase
  69 begins with an identifier, which is what we list here.  Future
  70 designers of extensions are strongly encouraged to pick
  71 non-conflicting identifiers.  Note that newphrase occurs several
  72 places in the RCS grammar, and a given extension may not be legal in
  73 all locations.  However, it seems better to reserve a particular
  74 identifier for all locations, to avoid confusion and complicated
  75 rules.
  76
  77    Identifier   Used by
  78    ----------   -------
  79    namespace    RCS library done at Silicon Graphics Inc. (SGI) in 1996
  80                 (a modified RCS 5.7--not sure it has any other name).
  81    dead         A set of RCS patches developed by Rich Pixley at
  82                 Cygnus about 1992.  These were for CVS, and predated
  83                 the current CVS death support, which uses a state "dead"
  84                 rather than a "dead" newphrase.
  85
  86 CVS does use newphrases to implement the `PreservePermissions'
  87 extension introduced in CVS 1.9.26.  The following new keywords are
  88 defined when PreservePermissions=yes:
  89
  90    owner
  91    group
  92    permissions
  93    special
  94    symlink
  95    hardlinks
  96
  97 The contents of the `owner' and `group' field should be a numeric uid
  98 and a numeric gid, respectively, representing the user and group who
  99 own the file.  The `permissions' field contains an octal integer,
 100 representing the permissions that should be applied to the file.  The
 101 `special' field contains two words; the first must be either `block'
 102 or `character', and the second is the file's device number.  The
 103 `symlink' field should be present only in files which are symbolic
 104 links to other files, and absent on all regular files.  The
 105 `hardlinks' field contains a list of filenames to which the current
 106 file is linked, in alphabetical order.  Because files often contain
 107 characters special to RCS, like `.' and sometimes even contain spaces
 108 or eight-bit characters, the filenames in the hardlinks field will
 109 usually be enclosed in RCS strings.  For example:
 110
 111         hardlinks       README @install.txt@ @Installation Notes@;
 112
 113 The hardlinks field should always include the name of the current
 114 file.  That is, in the repository file README,v, any hardlinks fields
 115 in the delta nodes should include `README'; CVS will not operate
 116 properly if this is not done.
 117
 118 The rules regarding keyword expansion are not documented along with
 119 the rest of the RCS file format; they are documented in the co(1)
 120 manpage in the RCS 5.7 distribution.  See also the "Keyword
 121 substitution" chapter of cvs.texinfo.  The co(1) manpage refers to
 122 special behavior if the log prefix for the $Log keyword is /* or (*.
 123 RCS 5.7 produces a warning whenever it behaves that way, and current
 124 versions of CVS do not handle this case in a special way (CVS 1.9 and
 125 earlier invoke RCS to perform keyword expansion).
 126
 127 Note that if the "expand" keyword is omitted from the RCS file, the
 128 default is "kv".
 129
 130 Note that the "comment {string};" syntax from rcsfile.5 specifies a
 131 comment leader, which affects expansion of the $Log keyword for old
 132 versions of RCS.  The comment leader is not used by RCS 5.7 or current
 133 versions of CVS.
 134
 135 Both RCS 5.7 and current versions of CVS handle the $Log keyword in a
 136 different way if the log message starts with "checked in with -k by ".
 137 I don't think this behavior is documented anywhere.
 138
 139 Here is a clarification regarding characters versus bytes in certain
 140 character sets like JIS and Big5:
 141
 142     The RCS file format, as described in the rcsfile(5) man page, is
 143     actually byte-oriented, not character-oriented, despite hints to
 144     the contrary in the man page.  This distinction is important for
 145     multibyte characters.  For example, if a multibyte character
 146     contains a `@' byte, the `@' must be doubled within strings in RCS
 147     files, since RCS uses `@' bytes as escapes.
 148
 149     This point is not an issue for encodings like ISO 8859, which do
 150     not have multibyte characters.  Nor is it an issue for encodings
 151     like UTF-8 and EUC-JIS, which never uses ASCII bytes within a
 152     multibyte character.  It is an issue only for multibyte encodings
 153     like JIS and BIG5, which _do_ usurp ASCII bytes.
 154
 155     If `@' doubling occurs within a multibyte char, the resulting RCS
 156     file is not a properly encoded text file.  Instead, it is a byte
 157     stream that does not use a consistent character encoding that can
 158     be understood by the usual text tools, since doubling `@' messes
 159     up the encoding.  This point affects only programs that examine
 160     the RCS files -- it doesn't affect the external RCS interface, as
 161     the RCS commands always give you the properly encoded text files
 162     and logs (assuming that you always check in properly encoded
 163     text).
 164
 165     CVS 1.10 (and earlier) probably has some bugs in this area on
 166     systems where a C "char" is signed and where the data contains
 167     bytes with the eighth bit set.
 168
 169 One common concern about the RCS file format is the fact that to get
 170 the head of a branch, one must apply deltas from the head of the trunk
 171 to the branchpoint, and then from the branchpoint to the head of the
 172 branch.  While more detailed analyses might be worth doing, we will
 173 note:
 174
 175     * The performance bottleneck for CVS generally is figuring out which
 176     files to operate on and that sort of thing, not applying deltas.
 177
 178     * Here is one quick test (probably not a very good test; a better test
 179     would use a normally sized file (say 50-200K) instead of a small one):
 180
 181         I just did a quick test with a small file (on a Sun Ultra 1/170E
 182         running Solaris 5.5.1), with 1000 revisions on the main branch and
 183         1000 revisions on branch that forked at the root (i.e., RCS revisions
 184         1.1, 1.2, ..., 1.1000, and branch revisions 1.1.1.1, 1.1.1.2, ...,
 185         1.1.1.1000).  It took about 0.15 seconds real time to check in the
 186         first revision, and about 0.6 seconds to check in and 0.3 seconds to
 187         retrieve revision 1.1.1.1000 (the worst case).
 188
 189     * Any attempt to "fix" this problem should be careful not to interfere
 190     with other features, such as lightweight creation of branches
 191     (particularly using CVS magic branches).
 192
 193 Diff follows:
 194
 195 (Note that in the following diff the old value for the Id keyword was:
 196     Id: rcsfile.5in,v 5.6 1995/06/05 08:28:35 eggert Exp
 197 and the new one was:
 198     Id: rcsfile.5in,v 5.7 1996/12/09 17:31:44 eggert Exp
 199 but since this file itself might be subject to keyword expansion I
 200 haven't included a diff for that fact).
 201
 202 ===================================================================
 203 RCS file: RCS/rcsfile.5in,v
 204 retrieving revision 5.6
 205 retrieving revision 5.7
 206 diff -u -r5.6 -r5.7
 207 --- rcsfile.5in 1995/06/05 08:28:35     5.6
 208 +++ rcsfile.5in 1996/12/09 17:31:44     5.7
 209 @@ -85,7 +85,8 @@
 210  .LP
 211  \f2sym\fP      ::=     {\f2digit\fP}* \f2idchar\fP {\f2idchar\fP | \f2digit\fP}*
 212  .LP
 213 -\f2idchar\fP   ::=     any visible graphic character except \f2special\fP
 214 +\f2idchar\fP   ::=     any visible graphic character,
 215 +               except \f2digit\fP or \f2special\fP
 216  .LP
 217  \f2special\fP  ::=     \f3$\fP | \f3,\fP | \f3.\fP | \f3:\fP | \f3;\fP | \f3@\fP
 218  .LP
 219 @@ -119,12 +120,23 @@
 220  the minute (00\-59),
 221  and
 222  .I ss
 223 -the second (00\-60).
 224 +the second (00\-59).
 225 +If
 226  .I Y
 227 -contains just the last two digits of the year
 228 -for years from 1900 through 1999,
 229 -and all the digits of years thereafter.
 230 -Dates use the Gregorian calendar; times use UTC.
 231 +contains exactly two digits,
 232 +they are the last two digits of a year from 1900 through 1999;
 233 +otherwise,
 234 +.I Y
 235 +contains all the digits of the year.
 236 +Dates use the Gregorian calendar.
 237 +Times use UTC, except that for portability's sake leap seconds are not allowed;
 238 +implementations that support leap seconds should output
 239 +.B 59
 240 +for
 241 +.I ss
 242 +during an inserted leap second, and should accept
 243 +.B 59
 244 +for a deleted leap second.
 245  .PP
 246  The
 247  .I newphrase
 248 @@ -144,16 +156,23 @@
 249  field in order of decreasing numbers.
 250  The
 251  .B head
 252 -field in the
 253 -.I admin
 254 -node points to the head of that sequence (i.e., contains
 255 +field points to the head of that sequence (i.e., contains
 256  the highest pair).
 257  The
 258  .B branch
 259 -node in the admin node indicates the default
 260 +field indicates the default
 261  branch (or revision) for most \*r operations.
 262  If empty, the default
 263  branch is the highest branch on the trunk.
 264 +The
 265 +.B symbols
 266 +field associates symbolic names with revisions.
 267 +For example, if the file contains
 268 +.B "symbols rr:1.1;"
 269 +then
 270 +.B rr
 271 +is a name for revision
 272 +.BR 1.1 .
 273  .PP
 274  All
 275  .I delta
 276