gnu/usr.bin/rcs/rcs/rcsfile.5

   1 .lf 1 ./rcsfile.5in
   2 .\" Set p to 1 if your formatter can handle pic output.
   3 .if t .nr p 1
   4 .de Id
   5 .ds Rv \\$3
   6 .ds Dt \\$4
   7 ..
   8 .Id $FreeBSD: src/gnu/usr.bin/rcs/rcs/rcsfile.5,v 1.5.2.1 2001/07/22 11:01:34 dd Exp $
   9 .Id $DragonFly: src/gnu/usr.bin/rcs/rcs/rcsfile.5,v 1.3 2007/01/17 17:56:23 y0netan1 Exp $
  10 .ds r \s-1RCS\s0
  11 .if n .ds - \%--
  12 .if t .ds - \(em
  13 .TH RCSFILE 5 \*(Dt GNU
  14 .SH NAME
  15 rcsfile \- format of RCS file
  16 .SH DESCRIPTION
  17 An \*r file's
  18 contents are described by the grammar
  19 below.
  20 .PP
  21 The text is free format: space, backspace, tab, newline, vertical
  22 tab, form feed, and carriage return (collectively,
  23 .IR "white space")
  24 have no significance except in strings.
  25 However, white space cannot appear within an id, num, or sym,
  26 and an \*r file must end with a newline.
  27 .PP
  28 Strings are enclosed by
  29 .BR @ .
  30 If a string contains a
  31 .BR @ ,
  32 it must be doubled;
  33 otherwise, strings can contain arbitrary binary data.
  34 .PP
  35 The meta syntax uses the following conventions: `|' (bar) separates
  36 alternatives; `{' and `}' enclose optional phrases; `{' and `}*' enclose
  37 phrases that can be repeated zero or more times;
  38 `{' and '}+' enclose phrases that must appear at least once and can be
  39 repeated;
  40 Terminal symbols are in
  41 .BR boldface ;
  42 nonterminal symbols are in
  43 .IR italics .
  44 .LP
  45 .nr w \w'\f3deltatext\fP '
  46 .nr y \w'\f3newphrase\fP '
  47 .if \nw<\ny .nr w \ny
  48 .nr x \w'\f3branches\fP'
  49 .nr y \w'{ \f3comment\fP'
  50 .if \nx<\ny .nr x \ny
  51 .nr y \w'\f3{ branch\fP'
  52 .if \nx<\ny .nr x \ny
  53 .ta \nwu +\w'::=  'u +\nxu+\w'  'u
  54 .fc #
  55 .nf
  56 \f2rcstext\fP   ::=     \f2admin\fP {\f2delta\fP}* \f2desc\fP {\f2deltatext\fP}*
  57 .LP
  58 \f2admin\fP     ::=     \f3head\fP      {\f2num\fP}\f3;\fP
  59                 { \f3branch\fP  {\f2num\fP}\f3;\fP }
  60                 \f3access\fP    {\f2id\fP}*\f3;\fP
  61                 \f3symbols\fP   {\f2sym\fP \f3:\fP \f2num\fP}*\f3;\fP
  62                 \f3locks\fP     {\f2id\fP \f3:\fP \f2num\fP}*\f3;\fP  {\f3strict  ;\fP}
  63                 { \f3comment\fP {\f2string\fP}\f3;\fP }
  64                 { \f3expand\fP  {\f2string\fP}\f3;\fP }
  65                 { \f2newphrase\fP }*
  66 .LP
  67 \f2delta\fP     ::=     \f2num\fP
  68                 \f3date\fP      \f2num\fP\f3;\fP
  69                 \f3author\fP    \f2id\fP\f3;\fP
  70                 \f3state\fP     {\f2id\fP}\f3;\fP
  71                 \f3branches\fP  {\f2num\fP}*\f3;\fP
  72                 \f3next\fP      {\f2num\fP}\f3;\fP
  73                 { \f3commitid\fP \f2id\fP\f3;\fP }
  74                 { \f2newphrase\fP }*
  75 .LP
  76 \f2desc\fP      ::=     \f3desc\fP      \f2string\fP
  77 .LP
  78 \f2deltatext\fP ::=     \f2num\fP
  79                 \f3log\fP       \f2string\fP
  80                 { \f2newphrase\fP }*
  81                 \f3text\fP      \f2string\fP
  82 .LP
  83 \f2num\fP       ::=     {\f2digit\fP | \f3.\fP}+
  84 .LP
  85 \f2digit\fP     ::=     \f30\fP | \f31\fP | \f32\fP | \f33\fP | \f34\fP | \f35\fP | \f36\fP | \f37\fP | \f38\fP | \f39\fP
  86 .LP
  87 \f2id\fP        ::=     {\f2num\fP} \f2idchar\fP {\f2idchar\fP | \f2num\fP}*
  88 .LP
  89 \f2sym\fP       ::=     {\f2digit\fP}* \f2idchar\fP {\f2idchar\fP | \f2digit\fP}*
  90 .LP
  91 \f2idchar\fP    ::=     any visible graphic character except \f2special\fP
  92 .LP
  93 \f2special\fP   ::=     \f3$\fP | \f3,\fP | \f3.\fP | \f3:\fP | \f3;\fP | \f3@\fP
  94 .LP
  95 \f2string\fP    ::=     \f3@\fP{any character, with \f3@\fP doubled}*\f3@\fP
  96 .LP
  97 \f2newphrase\fP ::=     \f2id\fP \f2word\fP* \f3;\fP
  98 .LP
  99 \f2word\fP      ::=     \f2id\fP | \f2num\fP | \f2string\fP | \f3:\fP
 100 .fi
 101 .PP
 102 Identifiers are case sensitive.  Keywords are in lower case only.
 103 The sets of keywords and identifiers can overlap.
 104 In most environments \*r uses the \s-1ISO\s0 8859/1 encoding:
 105 visible graphic characters are codes 041\-176 and 240\-377,
 106 and white space characters are codes 010\-015 and 040.
 107 .PP
 108 Dates, which appear after the
 109 .B date
 110 keyword, are of the form
 111 \f2Y\fP\f3.\fP\f2mm\fP\f3.\fP\f2dd\fP\f3.\fP\f2hh\fP\f3.\fP\f2mm\fP\f3.\fP\f2ss\fP,
 112 where
 113 .I Y
 114 is the year,
 115 .I mm
 116 the month (01\-12),
 117 .I dd
 118 the day (01\-31),
 119 .I hh
 120 the hour (00\-23),
 121 .I mm
 122 the minute (00\-59),
 123 and
 124 .I ss
 125 the second (00\-60).
 126 .I Y
 127 contains just the last two digits of the year
 128 for years from 1900 through 1999,
 129 and all the digits of years thereafter.
 130 Dates use the Gregorian calendar; times use UTC.
 131 .PP
 132 The
 133 .I commitid
 134 is followed by an
 135 .I id
 136 token. This token is intended to be unique across
 137 multiple files and is used to help group files as
 138 being a part of the same logical commit.
 139 This token must uniquely identify the commit
 140 operation that was applied to a set of RCS files.
 141 In particular, it must be unique among all the
 142 commitids in this file.
 143 .PP
 144 The
 145 .I newphrase
 146 productions in the grammar are reserved for future extensions
 147 to the format of \*r files.
 148 No
 149 .I newphrase
 150 will begin with any keyword already in use.
 151 .PP
 152 The
 153 .I delta
 154 nodes form a tree.  All nodes whose numbers
 155 consist of a single pair
 156 (e.g., 2.3, 2.1, 1.3, etc.)
 157 are on the trunk, and are linked through the
 158 .B next
 159 field in order of decreasing numbers.
 160 The
 161 .B head
 162 field in the
 163 .I admin
 164 node points to the head of that sequence (i.e., contains
 165 the highest pair).
 166 The
 167 .B branch
 168 node in the admin node indicates the default
 169 branch (or revision) for most \*r operations.
 170 If empty, the default
 171 branch is the highest branch on the trunk.
 172 .PP
 173 All
 174 .I delta
 175 nodes whose numbers consist of
 176 .RI 2 n
 177 fields
 178 .RI ( n \(>=2)
 179 (e.g., 3.1.1.1, 2.1.2.2, etc.)
 180 are linked as follows.
 181 All nodes whose first
 182 .RI 2 n \-1
 183 number fields are identical are linked through the
 184 .B next
 185 field in order of increasing numbers.
 186 For each such sequence,
 187 the
 188 .I delta
 189 node whose number is identical to the first
 190 .RI 2 n \-2
 191 number fields of the deltas on that sequence is called the branchpoint.
 192 The
 193 .B branches
 194 field of a node contains a list of the
 195 numbers of the first nodes of all sequences for which it is a branchpoint.
 196 This list is ordered in increasing numbers.
 197 .LP
 198 The following diagram shows an example of an \*r file's organization.
 199 .if !\np \{\
 200 .nf
 201 .vs 12
 202 .ne 36
 203 .cs 1 20
 204 .eo
 205
 206                            Head
 207                              |
 208                              |
 209                              v                        / \
 210                          ---------                   /   \
 211    / \          / \      |       |      / \         /     \
 212   /   \        /   \     |  2.1  |     /   \       /       \
 213  /     \      /     \    |       |    /     \     /         \
 214 /1.2.1.3\    /1.3.1.1\   |       |   /1.2.2.2\   /1.2.2.1.1.1\
 215 ---------    ---------   ---------   ---------   -------------
 216     ^            ^           |           ^             ^
 217     |            |           |           |             |
 218     |            |           v           |             |
 219    / \           |       ---------      / \            |
 220   /   \          |       \  1.3  /     /   \           |
 221  /     \         ---------\     /     /     \-----------
 222 /1.2.1.1\                  \   /     /1.2.2.1\
 223 ---------                   \ /      ---------
 224     ^                        |           ^
 225     |                        |           |
 226     |                        v           |
 227     |                    ---------       |
 228     |                    \  1.2  /       |
 229     ----------------------\     /---------
 230                            \   /
 231                             \ /
 232                              |
 233                              |
 234                              v
 235                          ---------
 236                          \  1.1  /
 237                           \     /
 238                            \   /
 239                             \ /
 240
 241 .ec
 242 .cs 1
 243 .vs
 244 .fi
 245 .\}
 246 .if \np \{\
 247 .lf 232
 248 .PS 4.250i 3.812i
 249 .\" -2.0625 -4.25 1.75 0
 250 .\" 0.000i 4.250i 3.812i 0.000i
 251 .nr 00 \n(.u
 252 .nf
 253 .nr 0x 1
 254 \h'3.812i'
 255 .sp -1
 256 .lf 242
 257 \h'2.062i-(\w'Head'u/2u)'\v'0.125i-(0v/2u)+0v+0.22m'Head
 258 .sp -1
 259 \h'2.062i'\v'0.250i'\D'l0.000i 0.500i'
 260 .sp -1
 261 \h'2.087i'\v'0.650i'\D'l-0.025i 0.100i'
 262 .sp -1
 263 \h'2.062i'\v'0.750i'\D'l-0.025i -0.100i'
 264 .sp -1
 265 \h'1.688i'\v'1.250i'\D'l0.750i 0.000i'
 266 .sp -1
 267 \h'2.438i'\v'1.250i'\D'l0.000i -0.500i'
 268 .sp -1
 269 \h'2.438i'\v'0.750i'\D'l-0.750i 0.000i'
 270 .sp -1
 271 \h'1.688i'\v'0.750i'\D'l0.000i 0.500i'
 272 .sp -1
 273 .lf 244
 274 \h'2.062i-(\w'2.1'u/2u)'\v'1.000i-(0v/2u)+0v+0.22m'2.1
 275 .sp -1
 276 \h'2.062i'\v'1.250i'\D'l0.000i 0.500i'
 277 .sp -1
 278 \h'2.087i'\v'1.650i'\D'l-0.025i 0.100i'
 279 .sp -1
 280 \h'2.062i'\v'1.750i'\D'l-0.025i -0.100i'
 281 .sp -1
 282 .lf 246
 283 \h'2.062i-(\w'1.3'u/2u)'\v'2.000i-(1v/2u)+0v+0.22m'1.3
 284 .sp -1
 285 \h'2.062i'\v'2.250i'\D'l-0.375i -0.500i'
 286 .sp -1
 287 \h'1.688i'\v'1.750i'\D'l0.750i 0.000i'
 288 .sp -1
 289 \h'2.438i'\v'1.750i'\D'l-0.375i 0.500i'
 290 .sp -1
 291 \h'1.875i'\v'2.000i'\D'~-0.500i 0.000i 0.000i -0.500i'
 292 .sp -1
 293 \h'1.350i'\v'1.600i'\D'l0.025i -0.100i'
 294 .sp -1
 295 \h'1.375i'\v'1.500i'\D'l0.025i 0.100i'
 296 .sp -1
 297 .lf 249
 298 \h'1.375i-(\w'1.3.1.1'u/2u)'\v'1.250i-(1v/2u)+1v+0.22m'1.3.1.1
 299 .sp -1
 300 \h'1.375i'\v'1.000i'\D'l-0.375i 0.500i'
 301 .sp -1
 302 \h'1.000i'\v'1.500i'\D'l0.750i 0.000i'
 303 .sp -1
 304 \h'1.750i'\v'1.500i'\D'l-0.375i -0.500i'
 305 .sp -1
 306 \h'2.062i'\v'2.250i'\D'l0.000i 0.500i'
 307 .sp -1
 308 \h'2.087i'\v'2.650i'\D'l-0.025i 0.100i'
 309 .sp -1
 310 \h'2.062i'\v'2.750i'\D'l-0.025i -0.100i'
 311 .sp -1
 312 .lf 252
 313 \h'2.062i-(\w'1.2'u/2u)'\v'3.000i-(1v/2u)+0v+0.22m'1.2
 314 .sp -1
 315 \h'2.062i'\v'3.250i'\D'l-0.375i -0.500i'
 316 .sp -1
 317 \h'1.688i'\v'2.750i'\D'l0.750i 0.000i'
 318 .sp -1
 319 \h'2.438i'\v'2.750i'\D'l-0.375i 0.500i'
 320 .sp -1
 321 \h'1.875i'\v'3.000i'\D'~-0.500i 0.000i -0.500i 0.000i -0.500i 0.000i 0.000i -0.500i'
 322 .sp -1
 323 \h'0.350i'\v'2.600i'\D'l0.025i -0.100i'
 324 .sp -1
 325 \h'0.375i'\v'2.500i'\D'l0.025i 0.100i'
 326 .sp -1
 327 .lf 255
 328 \h'0.375i-(\w'1.2.1.1'u/2u)'\v'2.250i-(1v/2u)+1v+0.22m'1.2.1.1
 329 .sp -1
 330 \h'0.375i'\v'2.000i'\D'l-0.375i 0.500i'
 331 .sp -1
 332 \h'0.000i'\v'2.500i'\D'l0.750i 0.000i'
 333 .sp -1
 334 \h'0.750i'\v'2.500i'\D'l-0.375i -0.500i'
 335 .sp -1
 336 \h'0.375i'\v'2.000i'\D'l0.000i -0.500i'
 337 .sp -1
 338 \h'0.350i'\v'1.600i'\D'l0.025i -0.100i'
 339 .sp -1
 340 \h'0.375i'\v'1.500i'\D'l0.025i 0.100i'
 341 .sp -1
 342 .lf 257
 343 \h'0.375i-(\w'1.2.1.3'u/2u)'\v'1.250i-(1v/2u)+1v+0.22m'1.2.1.3
 344 .sp -1
 345 \h'0.375i'\v'1.000i'\D'l-0.375i 0.500i'
 346 .sp -1
 347 \h'0.000i'\v'1.500i'\D'l0.750i 0.000i'
 348 .sp -1
 349 \h'0.750i'\v'1.500i'\D'l-0.375i -0.500i'
 350 .sp -1
 351 \h'2.250i'\v'3.000i'\D'~0.500i 0.000i 0.000i -0.500i'
 352 .sp -1
 353 \h'2.725i'\v'2.600i'\D'l0.025i -0.100i'
 354 .sp -1
 355 \h'2.750i'\v'2.500i'\D'l0.025i 0.100i'
 356 .sp -1
 357 .lf 261
 358 \h'2.750i-(\w'1.2.2.1'u/2u)'\v'2.250i-(1v/2u)+1v+0.22m'1.2.2.1
 359 .sp -1
 360 \h'2.750i'\v'2.000i'\D'l-0.375i 0.500i'
 361 .sp -1
 362 \h'2.375i'\v'2.500i'\D'l0.750i 0.000i'
 363 .sp -1
 364 \h'3.125i'\v'2.500i'\D'l-0.375i -0.500i'
 365 .sp -1
 366 \h'2.938i'\v'2.250i'\D'~0.500i 0.000i 0.000i -0.500i 0.000i -0.500i'
 367 .sp -1
 368 \h'3.413i'\v'1.350i'\D'l0.025i -0.100i'
 369 .sp -1
 370 \h'3.438i'\v'1.250i'\D'l0.025i 0.100i'
 371 .sp -1
 372 .lf 264
 373 \h'3.438i-(\w'\s-21.2.2.1.1.1\s0'u/2u)'\v'1.000i-(1v/2u)+1v+0.22m'\s-21.2.2.1.1.1\s0
 374 .sp -1
 375 \h'3.438i'\v'0.750i'\D'l-0.375i 0.500i'
 376 .sp -1
 377 \h'3.062i'\v'1.250i'\D'l0.750i 0.000i'
 378 .sp -1
 379 \h'3.812i'\v'1.250i'\D'l-0.375i -0.500i'
 380 .sp -1
 381 \h'2.750i'\v'2.000i'\D'l0.000i -0.500i'
 382 .sp -1
 383 \h'2.725i'\v'1.600i'\D'l0.025i -0.100i'
 384 .sp -1
 385 \h'2.750i'\v'1.500i'\D'l0.025i 0.100i'
 386 .sp -1
 387 .lf 267
 388 \h'2.750i-(\w'1.2.2.2'u/2u)'\v'1.250i-(1v/2u)+1v+0.22m'1.2.2.2
 389 .sp -1
 390 \h'2.750i'\v'1.000i'\D'l-0.375i 0.500i'
 391 .sp -1
 392 \h'2.375i'\v'1.500i'\D'l0.750i 0.000i'
 393 .sp -1
 394 \h'3.125i'\v'1.500i'\D'l-0.375i -0.500i'
 395 .sp -1
 396 \h'2.062i'\v'3.250i'\D'l0.000i 0.500i'
 397 .sp -1
 398 \h'2.087i'\v'3.650i'\D'l-0.025i 0.100i'
 399 .sp -1
 400 \h'2.062i'\v'3.750i'\D'l-0.025i -0.100i'
 401 .sp -1
 402 .lf 270
 403 \h'2.062i-(\w'1.1'u/2u)'\v'4.000i-(1v/2u)+0v+0.22m'1.1
 404 .sp -1
 405 \h'2.062i'\v'4.250i'\D'l-0.375i -0.500i'
 406 .sp -1
 407 \h'1.688i'\v'3.750i'\D'l0.750i 0.000i'
 408 .sp -1
 409 \h'2.438i'\v'3.750i'\D'l-0.375i 0.500i'
 410 .sp -1
 411 .sp 4.250i+1
 412 .if \n(00 .fi
 413 .br
 414 .nr 0x 0
 415 .lf 271
 416 .PE
 417 .lf 272
 418 .\}
 419 .SH IDENTIFICATION
 420 .de VL
 421 \\$2
 422 ..
 423 Author: Walter F. Tichy,
 424 Purdue University, West Lafayette, IN, 47907.
 425 .br
 426 Manual Page Revision: \*(Rv; Release Date: \*(Dt.
 427 .br
 428 Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
 429 .br
 430 Copyright \(co 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert.
 431 .SH SEE ALSO
 432 rcsintro(1), ci(1), co(1), ident(1), rcs(1), rcsclean(1), rcsdiff(1),
 433 rcsmerge(1), rlog(1)
 434 .br
 435 Walter F. Tichy,
 436 \*r\*-A System for Version Control,
 437 .I "Software\*-Practice & Experience"
 438 .BR 15 ,
 439 7 (July 1985), 637-654.