diff options
Diffstat (limited to 'gnu')
| -rw-r--r-- | gnu/usr.bin/cvs/doc/RCSFILES | 167 |
1 files changed, 7 insertions, 160 deletions
diff --git a/gnu/usr.bin/cvs/doc/RCSFILES b/gnu/usr.bin/cvs/doc/RCSFILES index 46503377901..0ac61aa1d42 100644 --- a/gnu/usr.bin/cvs/doc/RCSFILES +++ b/gnu/usr.bin/cvs/doc/RCSFILES @@ -1,4 +1,4 @@ -It would be nice if the RCS file format (which is implemented by a +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 @@ -24,37 +24,12 @@ 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 rcsfile.5 documentation only _very_ briefly touches on the order -of the revisions. The order _is_ important and CVS relies on it. -Here is an example of what I was able to find, based on the join3 -sanity.sh testcase (and the behavior I am documenting here seems to be -the same for RCS 5.7 and CVS 1.9.27): - - 1.1 -----------------> 1.2 - \---> 1.1.2.1 \---> 1.2.2.1 - -Here is how this shows up in the RCS file (omitting irrelevant parts): - - admin: head 1.2; - deltas: - 1.2 branches 1.2.2.1; next 1.1; - 1.1 branches 1.1.2.1; next; - 1.1.2.1 branches; next; - 1.2.2.1 branches; next; - deltatexts: - 1.2 - 1.2.2.1 - 1.1 - 1.1.2.1 - -Yes, the order seems to differ between the deltas and the deltatexts. -I have no idea how much of this should actually be considered part of -the RCS file format, and how much programs reading it should expect to -encounter any order. - -The rcsfile.5 grammar shows the {num} after "next" as optional; if it -is omitted then there is no next delta node (for example 1.1 or the -head of a branch will typically have no next). +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 @@ -62,134 +37,6 @@ 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 RCS file format allows quite a variety of extensions to be added -in a compatible manner by use of the "newphrase" feature documented in -rcsfile.5. We won't try to document extensions not used by CVS in any -detail, but we will briefly list them. Each occurrence of a newphrase -begins with an identifier, which is what we list here. Future -designers of extensions are strongly encouraged to pick -non-conflicting identifiers. Note that newphrase occurs several -places in the RCS grammar, and a given extension may not be legal in -all locations. However, it seems better to reserve a particular -identifier for all locations, to avoid confusion and complicated -rules. - - Identifier Used by - ---------- ------- - namespace RCS library done at Silicon Graphics Inc. (SGI) in 1996 - (a modified RCS 5.7--not sure it has any other name). - dead A set of RCS patches developed by Rich Pixley at - Cygnus about 1992. These were for CVS, and predated - the current CVS death support, which uses a state "dead" - rather than a "dead" newphrase. - -CVS does use newphrases to implement the `PreservePermissions' -extension introduced in CVS 1.9.26. The following new keywords are -defined when PreservePermissions=yes: - - owner - group - permissions - special - symlink - hardlinks - -The contents of the `owner' and `group' field should be a numeric uid -and a numeric gid, respectively, representing the user and group who -own the file. The `permissions' field contains an octal integer, -representing the permissions that should be applied to the file. The -`special' field contains two words; the first must be either `block' -or `character', and the second is the file's device number. The -`symlink' field should be present only in files which are symbolic -links to other files, and absent on all regular files. The -`hardlinks' field contains a list of filenames to which the current -file is linked, in alphabetical order. Because files often contain -characters special to RCS, like `.' and sometimes even contain spaces -or eight-bit characters, the filenames in the hardlinks field will -usually be enclosed in RCS strings. For example: - - hardlinks README @install.txt@ @Installation Notes@; - -The hardlinks field should always include the name of the current -file. That is, in the repository file README,v, any hardlinks fields -in the delta nodes should include `README'; CVS will not operate -properly if this is not done. - -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 if the "expand" keyword is omitted from the RCS file, the -default is "kv". - -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. - -Here is a clarification regarding characters versus bytes in certain -character sets like JIS and Big5: - - The RCS file format, as described in the rcsfile(5) man page, is - actually byte-oriented, not character-oriented, despite hints to - the contrary in the man page. This distinction is important for - multibyte characters. For example, if a multibyte character - contains a `@' byte, the `@' must be doubled within strings in RCS - files, since RCS uses `@' bytes as escapes. - - This point is not an issue for encodings like ISO 8859, which do - not have multibyte characters. Nor is it an issue for encodings - like UTF-8 and EUC-JIS, which never uses ASCII bytes within a - multibyte character. It is an issue only for multibyte encodings - like JIS and BIG5, which _do_ usurp ASCII bytes. - - If `@' doubling occurs within a multibyte char, the resulting RCS - file is not a properly encoded text file. Instead, it is a byte - stream that does not use a consistent character encoding that can - be understood by the usual text tools, since doubling `@' messes - up the encoding. This point affects only programs that examine - the RCS files -- it doesn't affect the external RCS interface, as - the RCS commands always give you the properly encoded text files - and logs (assuming that you always check in properly encoded - text). - - CVS 1.10 (and earlier) probably has some bugs in this area on - systems where a C "char" is signed and where the data contains - bytes with the eighth bit set. - -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: |