RCSFILES revision 26801
125839SpeterIt would be nice for the RCS file format (which is implemented by a 225839Spetergreat many tools, both free and non-free, both by calling GNU RCS and 325839Speterby reimplementing access to RCS files) were documented in some 425839Speterstandard separate from any one tool. But as far as I know no such 525839Speterstandard exists. Hence this file. 625839Speter 725839SpeterThe place to start is the rcsfile.5 manpage in the GNU RCS 5.7 825839Speterdistribution. Then look at the diff at the end of this file (which 925839Spetercontains a few fixes and clarifications to that manpage). 1025839Speter 1125839SpeterIf you are interested in MKS RCS, src/ci.c in GNU RCS 5.7 has a 1225839Spetercomment about their date format. However, as far as we know there 1325839Speterisn't really any document describing MKS's changes to the RCS file 1425839Speterformat. 1525839Speter 1625839SpeterThe rcsfile.5 manpage does not document what goes in the "text" field 1725839Speterfor each revision. The answer is that the head revision contains the 1825839Spetercontents of that revision and every other revision contain a bunch of 1925839Speteredits to produce that revision ("a" and "d" lines). The GNU diff 2025839Spetermanual (the version I looked at was for GNU diff 2.4) documents this 2125839Speterformat somewhat (as the "RCS output format"), but the presentation is 2225839Spetera bit confusing as it is all tangled up with the documentation of 2325839Speterseveral other output formats. If you just want some source code to 2425839Speterlook at, the part of CVS which applies these is RCS_deltas in 2525839Spetersrc/rcs.c. 2625839Speter 2725839SpeterThe first time I read rcsfile.5 I didn't really notice the part about 2825839Speterthe order of the revisions. This order _is_ important and CVS relies 2925839Speteron it. It is documented but it would be clearer if the example in 3025839Speterrcsfile.5 also showed the order of the revisions (and the "next" and 3125839Speter"branch" fields and anything else where it would be useful to have an 3225839Speterexample of how a revision tree is represented in an RCS file). 3325839Speter 3425839SpeterThere is one case where CVS uses CVS-specific, non-compatible changes 3525839Speterto the RCS file format, and this is magic branches. See cvs.texinfo 3625839Speterfor more information on them. CVS also sets the RCS state to "dead" 3725839Speterto indicate that a file does not exist in a given revision (this is 3825839Speterstored just as any other RCS state is). 3925839Speter 4026065SpeterThe RCS file format allows quite a variety of extensions to be added 4126065Speterin a compatible manner by use of the "newphrase" feature documented in 4226065Speterrcsfile.5. We won't try to document extensions not used by CVS in any 4326065Speterdetail, but we will briefly list them. Each occurrence of a newphrase 4426065Speterbegins with an identifier, which is what we list here. Future 4526065Speterdesigners of extensions are strongly encouraged to pick 4626065Speternon-conflicting identifiers. Note that newphrase occurs several 4726065Speterplaces in the RCS grammar, and a given extension may not be legal in 4826065Speterall locations. However, it seems better to reserve a particular 4926065Speteridentifier for all locations, to avoid confusion and complicated 5026065Speterrules. 5126065Speter 5226065Speter Identifier Used by 5326065Speter ---------- ------- 5426065Speter namespace RCS library done at Silicon Graphics Inc. (SGI) in 1996 5526065Speter (a modified RCS 5.7--not sure it has any other name). 5626801Speter dead A set of RCS patches developed by Rich Pixley at 5726801Speter Cygnus. These were for CVS, and predated the current 5826801Speter CVS death support, which does not require RCS changes. 5926065Speter 6025839SpeterThe rules regarding keyword expansion are not documented along with 6125839Speterthe rest of the RCS file format; they are documented in the co(1) 6225839Spetermanpage in the RCS 5.7 distribution. See also the "Keyword 6325839Spetersubstitution" chapter of cvs.texinfo. The co(1) manpage refers to 6425839Speterspecial behavior if the log prefix for the $Log keyword is /* or (*. 6525839SpeterRCS 5.7 produces a warning whenever it behaves that way, and current 6625839Speterversions of CVS do not handle this case in a special way (CVS 1.9 and 6725839Speterearlier invoke RCS to perform keyword expansion). 6825839Speter 6925839SpeterNote that the "comment {string};" syntax from rcsfile.5 specifies a 7025839Spetercomment leader, which affects expansion of the $Log keyword for old 7125839Speterversions of RCS. The comment leader is not used by RCS 5.7 or current 7225839Speterversions of CVS. 7325839Speter 7425839SpeterBoth RCS 5.7 and current versions of CVS handle the $Log keyword in a 7525839Speterdifferent way if the log message starts with "checked in with -k by ". 7625839SpeterI don't think this behavior is documented anywhere. 7725839Speter 7825839SpeterOne common concern about the RCS file format is the fact that to get 7925839Speterthe head of a branch, one must apply deltas from the head of the trunk 8025839Speterto the branchpoint, and then from the branchpoint to the head of the 8125839Speterbranch. While more detailed analyses might be worth doing, we will 8225839Speternote: 8325839Speter 8425839Speter * The performance bottleneck for CVS generally is figuring out which 8525839Speter files to operate on and that sort of thing, not applying deltas. 8625839Speter 8725839Speter * Here is one quick test (probably not a very good test; a better test 8825839Speter would use a normally sized file (say 50-200K) instead of a small one): 8925839Speter 9025839Speter I just did a quick test with a small file (on a Sun Ultra 1/170E 9125839Speter running Solaris 5.5.1), with 1000 revisions on the main branch and 9225839Speter 1000 revisions on branch that forked at the root (i.e., RCS revisions 9325839Speter 1.1, 1.2, ..., 1.1000, and branch revisions 1.1.1.1, 1.1.1.2, ..., 9425839Speter 1.1.1.1000). It took about 0.15 seconds real time to check in the 9525839Speter first revision, and about 0.6 seconds to check in and 0.3 seconds to 9625839Speter retrieve revision 1.1.1.1000 (the worst case). 9725839Speter 9825839Speter * Any attempt to "fix" this problem should be careful not to interfere 9925839Speter with other features, such as lightweight creation of branches 10025839Speter (particularly using CVS magic branches). 10125839Speter 10225839SpeterDiff follows: 10325839Speter 10425839Speter(Note that in the following diff the old value for the Id keyword was: 10525839Speter Id: rcsfile.5in,v 5.6 1995/06/05 08:28:35 eggert Exp 10625839Speterand the new one was: 10725839Speter Id: rcsfile.5in,v 5.7 1996/12/09 17:31:44 eggert Exp 10825839Speterbut since this file itself might be subject to keyword expansion I 10925839Speterhaven't included a diff for that fact). 11025839Speter 11125839Speter=================================================================== 11225839SpeterRCS file: RCS/rcsfile.5in,v 11325839Speterretrieving revision 5.6 11425839Speterretrieving revision 5.7 11525839Speterdiff -u -r5.6 -r5.7 11625839Speter--- rcsfile.5in 1995/06/05 08:28:35 5.6 11725839Speter+++ rcsfile.5in 1996/12/09 17:31:44 5.7 11825839Speter@@ -85,7 +85,8 @@ 11925839Speter .LP 12025839Speter \f2sym\fP ::= {\f2digit\fP}* \f2idchar\fP {\f2idchar\fP | \f2digit\fP}* 12125839Speter .LP 12225839Speter-\f2idchar\fP ::= any visible graphic character except \f2special\fP 12325839Speter+\f2idchar\fP ::= any visible graphic character, 12425839Speter+ except \f2digit\fP or \f2special\fP 12525839Speter .LP 12625839Speter \f2special\fP ::= \f3$\fP | \f3,\fP | \f3.\fP | \f3:\fP | \f3;\fP | \f3@\fP 12725839Speter .LP 12825839Speter@@ -119,12 +120,23 @@ 12925839Speter the minute (00\-59), 13025839Speter and 13125839Speter .I ss 13225839Speter-the second (00\-60). 13325839Speter+the second (00\-59). 13425839Speter+If 13525839Speter .I Y 13625839Speter-contains just the last two digits of the year 13725839Speter-for years from 1900 through 1999, 13825839Speter-and all the digits of years thereafter. 13925839Speter-Dates use the Gregorian calendar; times use UTC. 14025839Speter+contains exactly two digits, 14125839Speter+they are the last two digits of a year from 1900 through 1999; 14225839Speter+otherwise, 14325839Speter+.I Y 14425839Speter+contains all the digits of the year. 14525839Speter+Dates use the Gregorian calendar. 14625839Speter+Times use UTC, except that for portability's sake leap seconds are not allowed; 14725839Speter+implementations that support leap seconds should output 14825839Speter+.B 59 14925839Speter+for 15025839Speter+.I ss 15125839Speter+during an inserted leap second, and should accept 15225839Speter+.B 59 15325839Speter+for a deleted leap second. 15425839Speter .PP 15525839Speter The 15625839Speter .I newphrase 15725839Speter@@ -144,16 +156,23 @@ 15825839Speter field in order of decreasing numbers. 15925839Speter The 16025839Speter .B head 16125839Speter-field in the 16225839Speter-.I admin 16325839Speter-node points to the head of that sequence (i.e., contains 16425839Speter+field points to the head of that sequence (i.e., contains 16525839Speter the highest pair). 16625839Speter The 16725839Speter .B branch 16825839Speter-node in the admin node indicates the default 16925839Speter+field indicates the default 17025839Speter branch (or revision) for most \*r operations. 17125839Speter If empty, the default 17225839Speter branch is the highest branch on the trunk. 17325839Speter+The 17425839Speter+.B symbols 17525839Speter+field associates symbolic names with revisions. 17625839Speter+For example, if the file contains 17725839Speter+.B "symbols rr:1.1;" 17825839Speter+then 17925839Speter+.B rr 18025839Speter+is a name for revision 18125839Speter+.BR 1.1 . 18225839Speter .PP 18325839Speter All 18425839Speter .I delta 18525839Speter 186