Debian Codegraph @

upstream/debian-unstable/man5/rcsfile.5

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