166 lines
6.4 KiB
Plaintext
166 lines
6.4 KiB
Plaintext
It would be nice for the RCS file format (which is implemented by a
|
|
great many tools, both free and non-free, both by calling GNU RCS and
|
|
by reimplementing access to RCS files) were documented in some
|
|
standard separate from any one tool. But as far as I know no such
|
|
standard exists. Hence this file.
|
|
|
|
The place to start is the rcsfile.5 manpage in the GNU RCS 5.7
|
|
distribution. Then look at the diff at the end of this file (which
|
|
contains a few fixes and clarifications to that manpage).
|
|
|
|
If you are interested in MKS RCS, src/ci.c in GNU RCS 5.7 has a
|
|
comment about their date format. However, as far as we know there
|
|
isn't really any document describing MKS's changes to the RCS file
|
|
format.
|
|
|
|
The rcsfile.5 manpage does not document what goes in the "text" field
|
|
for each revision. The answer is that the head revision contains the
|
|
contents of that revision and every other revision contain a bunch of
|
|
edits to produce that revision ("a" and "d" lines). The GNU diff
|
|
manual (the version I looked at was for GNU diff 2.4) documents this
|
|
format somewhat (as the "RCS output format"), but the presentation is
|
|
a bit confusing as it is all tangled up with the documentation of
|
|
several other output formats. If you just want some source code to
|
|
look at, the part of CVS which applies these is RCS_deltas in
|
|
src/rcs.c.
|
|
|
|
The first time I read rcsfile.5 I didn't really notice the part about
|
|
the order of the revisions. This order _is_ important and CVS relies
|
|
on it. It is documented but it would be clearer if the example in
|
|
rcsfile.5 also showed the order of the revisions (and the "next" and
|
|
"branch" fields and anything else where it would be useful to have an
|
|
example of how a revision tree is represented in an RCS file).
|
|
|
|
There is one case where CVS uses CVS-specific, non-compatible changes
|
|
to the RCS file format, and this is magic branches. See cvs.texinfo
|
|
for more information on them. CVS also sets the RCS state to "dead"
|
|
to indicate that a file does not exist in a given revision (this is
|
|
stored just as any other RCS state is).
|
|
|
|
The rules regarding keyword expansion are not documented along with
|
|
the rest of the RCS file format; they are documented in the co(1)
|
|
manpage in the RCS 5.7 distribution. See also the "Keyword
|
|
substitution" chapter of cvs.texinfo. The co(1) manpage refers to
|
|
special behavior if the log prefix for the $Log keyword is /* or (*.
|
|
RCS 5.7 produces a warning whenever it behaves that way, and current
|
|
versions of CVS do not handle this case in a special way (CVS 1.9 and
|
|
earlier invoke RCS to perform keyword expansion).
|
|
|
|
Note that the "comment {string};" syntax from rcsfile.5 specifies a
|
|
comment leader, which affects expansion of the $Log keyword for old
|
|
versions of RCS. The comment leader is not used by RCS 5.7 or current
|
|
versions of CVS.
|
|
|
|
Both RCS 5.7 and current versions of CVS handle the $Log keyword in a
|
|
different way if the log message starts with "checked in with -k by ".
|
|
I don't think this behavior is documented anywhere.
|
|
|
|
One common concern about the RCS file format is the fact that to get
|
|
the head of a branch, one must apply deltas from the head of the trunk
|
|
to the branchpoint, and then from the branchpoint to the head of the
|
|
branch. While more detailed analyses might be worth doing, we will
|
|
note:
|
|
|
|
* The performance bottleneck for CVS generally is figuring out which
|
|
files to operate on and that sort of thing, not applying deltas.
|
|
|
|
* Here is one quick test (probably not a very good test; a better test
|
|
would use a normally sized file (say 50-200K) instead of a small one):
|
|
|
|
I just did a quick test with a small file (on a Sun Ultra 1/170E
|
|
running Solaris 5.5.1), with 1000 revisions on the main branch and
|
|
1000 revisions on branch that forked at the root (i.e., RCS revisions
|
|
1.1, 1.2, ..., 1.1000, and branch revisions 1.1.1.1, 1.1.1.2, ...,
|
|
1.1.1.1000). It took about 0.15 seconds real time to check in the
|
|
first revision, and about 0.6 seconds to check in and 0.3 seconds to
|
|
retrieve revision 1.1.1.1000 (the worst case).
|
|
|
|
* Any attempt to "fix" this problem should be careful not to interfere
|
|
with other features, such as lightweight creation of branches
|
|
(particularly using CVS magic branches).
|
|
|
|
Diff follows:
|
|
|
|
(Note that in the following diff the old value for the Id keyword was:
|
|
Id: rcsfile.5in,v 5.6 1995/06/05 08:28:35 eggert Exp
|
|
and the new one was:
|
|
Id: rcsfile.5in,v 5.7 1996/12/09 17:31:44 eggert Exp
|
|
but since this file itself might be subject to keyword expansion I
|
|
haven't included a diff for that fact).
|
|
|
|
===================================================================
|
|
RCS file: RCS/rcsfile.5in,v
|
|
retrieving revision 5.6
|
|
retrieving revision 5.7
|
|
diff -u -r5.6 -r5.7
|
|
--- rcsfile.5in 1995/06/05 08:28:35 5.6
|
|
+++ rcsfile.5in 1996/12/09 17:31:44 5.7
|
|
@@ -85,7 +85,8 @@
|
|
.LP
|
|
\f2sym\fP ::= {\f2digit\fP}* \f2idchar\fP {\f2idchar\fP | \f2digit\fP}*
|
|
.LP
|
|
-\f2idchar\fP ::= any visible graphic character except \f2special\fP
|
|
+\f2idchar\fP ::= any visible graphic character,
|
|
+ except \f2digit\fP or \f2special\fP
|
|
.LP
|
|
\f2special\fP ::= \f3$\fP | \f3,\fP | \f3.\fP | \f3:\fP | \f3;\fP | \f3@\fP
|
|
.LP
|
|
@@ -119,12 +120,23 @@
|
|
the minute (00\-59),
|
|
and
|
|
.I ss
|
|
-the second (00\-60).
|
|
+the second (00\-59).
|
|
+If
|
|
.I Y
|
|
-contains just the last two digits of the year
|
|
-for years from 1900 through 1999,
|
|
-and all the digits of years thereafter.
|
|
-Dates use the Gregorian calendar; times use UTC.
|
|
+contains exactly two digits,
|
|
+they are the last two digits of a year from 1900 through 1999;
|
|
+otherwise,
|
|
+.I Y
|
|
+contains all the digits of the year.
|
|
+Dates use the Gregorian calendar.
|
|
+Times use UTC, except that for portability's sake leap seconds are not allowed;
|
|
+implementations that support leap seconds should output
|
|
+.B 59
|
|
+for
|
|
+.I ss
|
|
+during an inserted leap second, and should accept
|
|
+.B 59
|
|
+for a deleted leap second.
|
|
.PP
|
|
The
|
|
.I newphrase
|
|
@@ -144,16 +156,23 @@
|
|
field in order of decreasing numbers.
|
|
The
|
|
.B head
|
|
-field in the
|
|
-.I admin
|
|
-node points to the head of that sequence (i.e., contains
|
|
+field points to the head of that sequence (i.e., contains
|
|
the highest pair).
|
|
The
|
|
.B branch
|
|
-node in the admin node indicates the default
|
|
+field indicates the default
|
|
branch (or revision) for most \*r operations.
|
|
If empty, the default
|
|
branch is the highest branch on the trunk.
|
|
+The
|
|
+.B symbols
|
|
+field associates symbolic names with revisions.
|
|
+For example, if the file contains
|
|
+.B "symbols rr:1.1;"
|
|
+then
|
|
+.B rr
|
|
+is a name for revision
|
|
+.BR 1.1 .
|
|
.PP
|
|
All
|
|
.I delta
|
|
|