Debian Codegraph @

upstream/debian-unstable/man1/rcs.1

raw
1 .ds Rv 5.10.1
2 .ds Dt 2025-12-02
3 .ds i \&\s-1ISO\s0
4 .ds r \&\s-1RCS\s0
5 .ds u \&\s-1UTC\s0
6 .ds o \*r file
7 .if n .ds - \%--
8 .if t .ds - \(em
9 .if !\n(.g \{\
10 . if !\w|\*(lq| \{\
11 . ds lq ``
12 . if \w'\(lq' .ds lq "\(lq
13 . \}
14 . if !\w|\*(rq| \{\
15 . ds rq ''
16 . if \w'\(rq' .ds rq "\(rq
17 . \}
18 .\}
19 .TH RCS 1 "\*(Dt" "GNU RCS \*(Rv"
20 .SH NAME
21 rcs \- change \*o attributes
22 .SH SYNOPSIS
23 .B rcs
24 .IR "options file " .\|.\|.
25 .SH DESCRIPTION
26 .B rcs
27 creates new \*os or changes attributes of existing ones.
28 An \*o contains multiple revisions of text,
29 an access list, a change log,
30 descriptive text,
31 and some control attributes.
32 For
33 .B rcs
34 to work, the caller's login name must be on the access list,
35 except if the access list is empty, the caller is the owner of the file
36 or the superuser, or
37 the
38 .B \-i
39 option is present.
40 .PP
41 Filenames matching an \*r suffix denote \*os;
42 all others denote working files.
43 Names are paired as explained in
44 .BR ci (1).
45 Revision numbers use the syntax described in
46 .BR ci (1).
47 .SH OPTIONS
48 .TP
49 .B \-i
50 Create and initialize a new \*o, but do not deposit any revision.
51 If the \*o name has no directory component, try to place it
52 first into the subdirectory
53 .BR ./RCS ,
54 and then into the current directory.
55 If the \*o
56 already exists, print an error message.
57 .TP
58 .BI \-a "logins"
59 Append the login names appearing in the comma-separated list
60 .I logins
61 to the access list of the \*o.
62 .TP
63 .BI \-A "oldfile"
64 Append the access list of
65 .I oldfile
66 to the access list of the \*o.
67 .TP
68 .BR \-e [\f2logins\fP]
69 Erase the login names appearing in the comma-separated list
70 .I logins
71 from the access list of the \*o.
72 If
73 .I logins
74 is omitted, erase the entire access list.
75 .TP
76 .BR \-b [\f2rev\fP]
77 Set the default branch to
78 .IR rev .
79 If
80 .I rev
81 is omitted, the default
82 branch is reset to the (dynamically) highest branch on the trunk.
83 .TP
84 .BI \-c string
85 Set the comment leader to
86 .IR string .
87 An initial
88 .BR ci ,
89 or an
90 .B "rcs\ \-i"
91 without
92 .BR \-c ,
93 guesses the comment leader from the suffix of the working file name.
94 .RS
95 .PP
96 This option is obsolescent, since \*r normally uses the preceding
97 .B $\&Log$
98 line's prefix when inserting log lines during checkout (see
99 .BR co (1)).
100 However, older versions of \*r use the comment leader instead of the
101 .B $\&Log$
102 line's prefix, so
103 if you plan to access a file with both old and new versions of \*r,
104 make sure its comment leader matches its
105 .B $\&Log$
106 line prefix.
107 .RE
108 .TP
109 .BI \-k subst
110 Set the default keyword substitution to
111 .IR subst .
112 The effect of keyword substitution is described in
113 .BR co (1).
114 Giving an explicit
115 .B \-k
116 option to
117 .BR co ,
118 .BR rcsdiff ,
119 and
120 .B rcsmerge
121 overrides this default.
122 Beware
123 .BR "rcs\ \-kv",
124 because
125 .B \-kv
126 is incompatible with
127 .BR "co\ \-l".
128 Use
129 .B "rcs\ \-kkv"
130 to restore the normal default keyword substitution.
131 .TP
132 .BR \-l [\f2rev\fP]
133 Lock the revision with number
134 .IR rev .
135 If a branch is given, lock the latest revision on that branch.
136 If
137 .I rev
138 is omitted, lock the latest revision on the default branch.
139 Locking prevents overlapping changes.
140 If someone else already holds the lock, the lock is broken as with
141 .B "rcs\ \-u"
142 (see below).
143 .TP
144 .BR \-u [\f2rev\fP]
145 Unlock the revision with number
146 .IR rev .
147 If a branch is given, unlock the latest revision on that branch.
148 If
149 .I rev
150 is omitted, remove the latest lock held by the caller.
151 Normally, only the locker of a revision can unlock it.
152 Somebody else unlocking a revision breaks the lock.
153 If RCS was configured
154 .BR "\-\-with-mailer" ,
155 then this causes a mail message to be sent to the original locker.
156 The message contains a commentary solicited from the breaker.
157 The commentary is terminated by end-of-file or by a line containing
158 .BR \&. "\ by"
159 itself.
160 .TP
161 .B \-L
162 Set locking to
163 .IR strict .
164 Strict locking means that the owner
165 of an \*o is not exempt from locking for checkin.
166 This option should be used for files that are shared.
167 .TP
168 .B \-U
169 Set locking to non-strict. Non-strict locking means that the owner of
170 a file need not lock a revision for checkin.
171 This option should
172 .I not
173 be used for files that are shared.
174 Whether default locking is strict is determined by your system administrator,
175 but it is normally strict.
176 .TP
177 \f3\-m\fP\f2rev\fP\f3:\fP[\f2msg\fP]
178 Replace revision
179 .IR rev 's
180 log message with
181 .IR msg .
182 If
183 .I msg
184 is omitted, it defaults to "*** empty log message ***".
185 .TP
186 .B \-M
187 Do not send mail when breaking somebody else's lock.
188 This option is not meant for casual use;
189 it is meant for programs that warn users by other means, and invoke
190 .B "rcs\ \-u"
191 only as a low-level lock-breaking operation.
192 .TP
193 \f3\-n\fP\f2name\fP[\f3:\fP[\f2rev\fP]]
194 Associate the symbolic name
195 .I name
196 with the branch or
197 revision
198 .IR rev .
199 Delete the symbolic name if both
200 .B :
201 and
202 .I rev
203 are omitted; otherwise, print an error message if
204 .I name
205 is already associated with
206 another number.
207 If
208 .I rev
209 is symbolic, it is expanded before association.
210 A
211 .I rev
212 consisting of a branch number followed by a
213 .B .\&
214 stands for the current latest revision in the branch.
215 A
216 .B :
217 with an empty
218 .I rev
219 stands for the current latest revision on the default branch,
220 normally the trunk.
221 For example,
222 .BI "rcs\ \-n" name ":\ RCS/*"
223 associates
224 .I name
225 with the current latest revision of all the named \*os;
226 this contrasts with
227 .BI "rcs\ \-n" name ":$\ RCS/*"
228 which associates
229 .I name
230 with the revision numbers extracted from keyword strings
231 in the corresponding working files.
232 .TP
233 \f3\-N\fP\f2name\fP[\f3:\fP[\f2rev\fP]]
234 Act like
235 .BR \-n ,
236 except override any previous assignment of
237 .IR name .
238 .TP
239 .BI \-o range
240 deletes (\*(lqoutdates\*(rq) the revisions given by
241 .IR range .
242 A range consisting of a single revision number means that revision.
243 A range consisting of a branch number means the latest revision on that
244 branch.
245 A range of the form
246 .IB rev1 : rev2
247 means
248 revisions
249 .I rev1
250 to
251 .I rev2
252 on the same branch,
253 .BI : rev
254 means from the beginning of the branch containing
255 .I rev
256 up to and including
257 .IR rev ,
258 and
259 .IB rev :
260 means
261 from revision
262 .I rev
263 to the end of the branch containing
264 .IR rev .
265 None of the outdated revisions can have branches or locks.
266 .TP
267 .B \-q
268 Run quietly; do not print diagnostics.
269 .TP
270 .B \-I
271 Run interactively, even if the standard input is not a terminal.
272 .TP
273 .B \-s\f2state\fP\f1[\fP:\f2rev\fP\f1]\fP
274 Set the state attribute of the revision
275 .I rev
276 to
277 .IR state .
278 If
279 .I rev
280 is a branch number, assume the latest revision on that branch.
281 If
282 .I rev
283 is omitted, assume the latest revision on the default branch.
284 Any identifier is acceptable for
285 .IR state .
286 A useful set of states
287 is
288 .B Exp
289 (for experimental),
290 .B Stab
291 (for stable), and
292 .B Rel
293 (for
294 released).
295 By default,
296 .BR ci (1)
297 sets the state of a revision to
298 .BR Exp .
299 .TP
300 .BR \-t [\f2file\fP]
301 Write descriptive text from the contents of the named
302 .I file
303 into the \*o, deleting the existing text.
304 The
305 .IR file
306 name cannot begin with
307 .BR \- .
308 If
309 .I file
310 is omitted, obtain the text from standard input,
311 terminated by end-of-file or by a line containing
312 .BR \&. "\ by"
313 itself.
314 Prompt for the text if interaction is possible; see
315 .BR \-I .
316 With
317 .BR \-i ,
318 descriptive text is obtained
319 even if
320 .B \-t
321 is not given.
322 .TP
323 .BI \-t\- string
324 Write descriptive text from the
325 .I string
326 into the \*o, deleting the existing text.
327 .TP
328 .B \-T
329 Preserve the modification time on the \*o
330 unless a revision is removed.
331 This option can suppress extensive recompilation caused by a
332 .BR make (1)
333 dependency of some copy of the working file on the \*o.
334 Use this option with care; it can suppress recompilation even when it is needed,
335 i.e. when a change to the \*o
336 would mean a change to keyword strings in the working file.
337 .TP
338 .BI \-V
339 Print \*r's version number.
340 .TP
341 .BI \-V n
342 Emulate \*r version
343 .IR n .
344 See
345 .BR co (1)
346 for details.
347 .TP
348 .BI \-x "suffixes"
349 Use
350 .I suffixes
351 to characterize \*os.
352 See
353 .BR ci (1)
354 for details.
355 .TP
356 .BI \-z zone
357 Use
358 .I zone
359 as the default time zone.
360 This option has no effect;
361 it is present for compatibility with other \*r commands.
362 .PP
363 At least one explicit option must be given,
364 to ensure compatibility with future planned extensions
365 to the
366 .B rcs
367 command.
368 .SH COMPATIBILITY
369 The
370 .BI \-b rev
371 option generates an \*o that cannot be parsed by \*r version 3 or earlier.
372 .PP
373 The
374 .BI \-k subst
375 options (except
376 .BR \-kkv )
377 generate an \*o that cannot be parsed by \*r version 4 or earlier.
378 .PP
379 Use
380 .BI "rcs \-V" n
381 to make an \*o acceptable to \*r version
382 .I n
383 by discarding information that would confuse version
384 .IR n .
385 .PP
386 \*r version 5.5 and earlier does not support the
387 .B \-x
388 option, and requires a
389 .B ,v
390 suffix on an \*o name.
391 .SH FILES
392 .B rcs
393 accesses files much as
394 .BR ci (1)
395 does,
396 except that it uses the effective user for all accesses,
397 it does not write the working file or its directory,
398 and it does not even read the working file unless a revision number of
399 .B $
400 is specified.
401 .SH ENVIRONMENT
402 .TP
403 .B \s-1RCSINIT\s0
404 Options prepended to the argument list, separated by spaces.
405 A backslash escapes spaces within an option.
406 The
407 .B \s-1RCSINIT\s0
408 options are prepended to the argument lists of most \*r commands.
409 Useful
410 .B \s-1RCSINIT\s0
411 options include
412 .BR \-q ,
413 .BR \-V ,
414 .BR \-x ,
415 and
416 .BR \-z .
417 .TP
418 .B \s-1RCS_MEM_LIMIT\s0
419 Normally, for speed, commands either memory map or copy into memory
420 the \*o if its size is less than the
421 .IR memory-limit ,
422 currently defaulting to ``unlimited''.
423 Otherwise (or if the initially-tried speedy ways fail),
424 the commands fall back to using
425 standard i/o routines.
426 You can adjust the memory limit by setting
427 .B \s-1RCS_MEM_LIMIT\s0
428 to a numeric value
429 .IR lim
430 (measured in kilobytes).
431 An empty value is silently ignored.
432 As a side effect, specifying
433 .B \s-1RCS_MEM_LIMIT\s0
434 inhibits fall-back to slower routines.
435 .TP
436 .B \s-1TMPDIR\s0
437 Name of the temporary directory.
438 If not set, the environment variables
439 .B \s-1TMP\s0
440 and
441 .B \s-1TEMP\s0
442 are inspected instead and the first value found is taken;
443 if none of them are set,
444 a host-dependent default is used, typically
445 .BR /tmp .
446 .SH DIAGNOSTICS
447 The \*o name and the revisions outdated are written to
448 the diagnostic output.
449 The exit status is zero if and only if all operations were successful.
450 .ds EY 1990, 1991, 1992, 1993, 1994, 1995
451 .SH IDENTIFICATION
452 Author: Walter F. Tichy.
453 .br
454 Manual Page Revision: \*(Rv; Release Date: \*(Dt.
455 .br
456 Copyright \(co 2010-2022 Thien-Thi Nguyen.
457 .br
458 Copyright \(co \*(EY Paul Eggert.
459 .br
460 Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
461 .br
462 .SH "SEE ALSO"
463 .BR co (1),
464 .BR ci (1),
465 .BR ident (1),
466 .BR rcsclean (1),
467 .BR rcsdiff (1),
468 .BR rcsmerge (1),
469 .BR rlog (1),
470 .BR rcsfile (5).
471 .PP
472 Walter F. Tichy,
473 \*r\*-A System for Version Control,
474 .I "Software\*-Practice & Experience"
475 .BR 15 ,
476 7 (July 1985), 637-654.
477 .PP
478 The full documentation for \*r is maintained as a Texinfo manual.
479 If the
480 .BR info (1)
481 and \*r programs are properly installed at your site, the command
482 .IP
483 .B info rcs
484 .PP
485 should give you access to the complete manual.
486 Additionally, the \*r homepage:
487 .IP
488 .B http://www.gnu.org/software/rcs/
489 .PP
490 has news and links to the latest release, development site, etc.
491 .SH BUGS
492 A catastrophe (e.g. a system crash) can cause \*r to leave behind
493 a semaphore file that causes later invocations of \*r to claim
494 that the \*o is in use.
495 To fix this, remove the semaphore file.
496 A semaphore file's name typically begins with
497 .B ,
498 or ends with
499 .BR _ .
500 .PP
501 The separator for revision ranges in the
502 .B \-o
503 option used to be
504 .B \-
505 instead of
506 .BR : ,
507 but this leads to confusion when symbolic names contain
508 .BR \- .
509 For backwards compatibility
510 .B "rcs \-o"
511 still supports the old
512 .B \-
513 separator, but it warns about this obsolete use.
514 .PP
515 Symbolic names need not refer to existing revisions or branches.
516 For example, the
517 .B \-o
518 option does not remove symbolic names for the outdated revisions; you must use
519 .B \-n
520 to remove the names.
521 .br