Penguin
Recent Changes
Annotated edit history of ci(1) version 1 showing authors affecting page license. View with all changes included.
Rev Author # Line
1 perry 1 CI
2 !!!CI
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 FILE NAMING
8 EXAMPLES
9 FILE MODES
10 FILES
11 SETUID USE
12 ENVIRONMENT
13 DIAGNOSTICS
14 IDENTIFICATION
15 SEE ALSO
16 ----
17 !!NAME
18
19
20 ci - check in RCS revisions
21 !!SYNOPSIS
22
23
24 __ci__ [[''options''] ''file'' ...
25 !!DESCRIPTION
26
27
28 __ci__ stores new revisions into RCS
29 files. Each pathname matching an RCS suffix
30 is taken to be an RCS file. All others are
31 assumed to be working files containing new revisions.
32 __ci__ deposits the contents of each working file into
33 the corresponding RCS file. If only a working
34 file is given, __ci__ tries to find the corresponding
35 RCS file in an RCS
36 subdirectory and then in the working file's directory. For
37 more details, see FILE NAMING
38 below.
39
40
41 For __ci__ to work, the caller's login must be on the
42 access list, except if the access list is empty or the
43 caller is the superuser or the owner of the file. To append
44 a new revision to an existing branch, the tip revision on
45 that branch must be locked by the caller. Otherwise, only a
46 new branch can be created. This restriction is not enforced
47 for the owner of the file if non-strict locking is used (see
48 rcs(1)). A lock held by someone else can be broken
49 with the __rcs__ command.
50
51
52 Unless the __-f__ option is given, __ci__ checks
53 whether the revision to be deposited differs from the
54 preceding one. If not, instead of creating a new revision
55 __ci__ reverts to the preceding one. To revert, ordinary
56 __ci__ removes the working file and any lock; __ci
57 -l__ keeps and __ci -u__ removes any lock, and then
58 they both generate a new working file much as if __co
59 -l__ or __co -u__ had been applied to the preceding
60 revision. When reverting, any __-n__ and __-s__
61 options apply to the preceding revision.
62
63
64 For each revision deposited, __ci__ prompts for a log
65 message. The log message should summarize the change and
66 must be terminated by end-of-file or by a line containing
67 __.__ by itself. If several files are checked in
68 __ci__ asks whether to reuse the previous log message. If
69 the standard input is not a terminal, __ci__ suppresses
70 the prompt and uses the same log message for all files. See
71 also __-m__.
72
73
74 If the RCS file does not exist, __ci__
75 creates it and deposits the contents of the working file as
76 the initial revision (default number: __1.1__). The
77 access list is initialized to empty. Instead of the log
78 message, __ci__ requests descriptive text (see __-t__
79 below).
80
81
82 The number ''rev'' of the deposited revision can be given
83 by any of the options __-f__, __-i__, __-I__,
84 __-j__, __-k__, __-l__, __-M__, __-q__,
85 __-r__, or __-u__. ''rev'' can be symbolic,
86 numeric, or mixed. Symbolic names in ''rev'' must already
87 be defined; see the __-n__ and __-N__ options for
88 assigning names during checkin. If ''rev'' is __$__,
89 __ci__ determines the revision number from keyword values
90 in the working file.
91
92
93 If ''rev'' begins with a period, then the default branch
94 (normally the trunk) is prepended to it. If ''rev'' is a
95 branch number followed by a period, then the latest revision
96 on that branch is used.
97
98
99 If ''rev'' is a revision number, it must be higher than
100 the latest one on the branch to which ''rev'' belongs, or
101 must start a new branch.
102
103
104 If ''rev'' is a branch rather than a revision number, the
105 new revision is appended to that branch. The level number is
106 obtained by incrementing the tip revision number of that
107 branch. If ''rev'' indicates a non-existing branch, that
108 branch is created with the initial revision numbered
109 ''rev''__.1__.
110
111
112 If ''rev'' is omitted, __ci__ tries to derive the new
113 revision number from the caller's last lock. If the caller
114 has locked the tip revision of a branch, the new revision is
115 appended to that branch. The new revision number is obtained
116 by incrementing the tip revision number. If the caller
117 locked a non-tip revision, a new branch is started at that
118 revision by incrementing the highest branch number at that
119 revision. The default initial branch and level numbers are
120 __1__.
121
122
123 If ''rev'' is omitted and the caller has no lock, but
124 owns the file and locking is not set to ''strict'', then
125 the revision is appended to the default branch (normally the
126 trunk; see the __-b__ option of
127 rcs(1)).
128
129
130 Exception: On the trunk, revisions can be appended to the
131 end, but not inserted.
132 !!OPTIONS
133
134
135 __-r__''rev''
136
137
138 Check in revision ''rev''.
139
140
141 __-r__
142
143
144 The bare __-r__ option (without any revision) has an
145 unusual meaning in __ci__. With other RCS
146 commands, a bare __-r__ option specifies the most recent
147 revision on the default branch, but with __ci__, a bare
148 __-r__ option reestablishes the default behavior of
149 releasing a lock and removing the working file, and is used
150 to override any default __-l__ or __-u__ options
151 established by shell aliases or scripts.
152
153
154 __-l__[[''rev'']
155
156
157 works like __-r__, except it performs an additional __co
158 -l__ for the deposited revision. Thus, the deposited
159 revision is immediately checked out again and locked. This
160 is useful for saving a revision although one wants to
161 continue editing it after the checkin.
162
163
164 __-u__[[''rev'']
165
166
167 works like __-l__, except that the deposited revision is
168 not locked. This lets one read the working file immediately
169 after checkin.
170
171
172 The __-l__, bare __-r__, and __-u__ options are
173 mutually exclusive and silently override each other. For
174 example, __ci -u -r__ is equivalent to __ci -r__
175 because bare __-r__ overrides __-u__.
176
177
178 __-f__[[''rev'']
179
180
181 forces a deposit; the new revision is deposited even it is
182 not different from the preceding one.
183
184
185 __-k__[[''rev'']
186
187
188 searches the working file for keyword values to determine
189 its revision number, creation date, state, and author (see
190 co(1)), and assigns these values to the deposited
191 revision, rather than computing them locally. It also
192 generates a default login message noting the login of the
193 caller and the actual checkin date. This option is useful
194 for software distribution. A revision that is sent to
195 several sites should be checked in with the __-k__ option
196 at these sites to preserve the original number, date,
197 author, and state. The extracted keyword values and the
198 default log message can be overridden with the options
199 __-d__, __-m__, __-s__, __-w__, and any option
200 that carries a revision number.
201
202
203 __-q__[[''rev'']
204
205
206 quiet mode; diagnostic output is not printed. A revision
207 that is not different from the preceding one is not
208 deposited, unless __-f__ is given.
209
210
211 __-i__[[''rev'']
212
213
214 initial checkin; report an error if the RCS
215 file already exists. This avoids race conditions in certain
216 applications.
217
218
219 __-j__[[''rev'']
220
221
222 just checkin and do not initialize; report an error if the
223 RCS file does not already exist.
224
225
226 __-I__[[''rev'']
227
228
229 interactive mode; the user is prompted and questioned even
230 if the standard input is not a terminal.
231
232
233 __-d__[[''date'']
234
235
236 uses ''date'' for the checkin date and time. The
237 ''date'' is specified in free format as explained in
238 co(1). This is useful for lying about the checkin
239 date, and for __-k__ if no date is available. If
240 ''date'' is empty, the working file's time of last
241 modification is used.
242
243
244 __-M__[[''rev'']
245
246
247 Set the modification time on any new working file to be the
248 date of the retrieved revision. For example, __ci -d -M
249 -u__ ''f'' does not alter ''f'''s modification time,
250 even if ''f'''s contents change due to keyword
251 substitution. Use this option with care; it can confuse
252 make(1).
253
254
255 __-m__''msg''
256
257
258 uses the string ''msg'' as the log message for all
259 revisions checked in. By convention, log messages that start
260 with __#__ are comments and are ignored by programs like
261 GNU Emacs's __vc__ package. Also, log messages that start
262 with __{__''clumpname''__}__ (followed by white
263 space) are meant to be clumped together if possible, even if
264 they are associated with different files; the
265 __{__''clumpname''__}__ label is used only for
266 clumping, and is not considered to be part of the log
267 message itself.
268
269
270 __-n__''name''
271
272
273 assigns the symbolic name ''name'' to the number of the
274 checked-in revision. __ci__ prints an error message if
275 ''name'' is already assigned to another
276 number.
277
278
279 __-N__''name''
280
281
282 same as __-n__, except that it overrides a previous
283 assignment of ''name''.
284
285
286 __-s__''state''
287
288
289 sets the state of the checked-in revision to the identifier
290 ''state''. The default state is __Exp__.
291
292
293 __-t__''file''
294
295
296 writes descriptive text from the contents of the named
297 ''file'' into the RCS file, deleting the
298 existing text. The ''file'' cannot begin with
299 __-__.
300
301
302 __-t-__''string''
303
304
305 Write descriptive text from the ''string'' into the
306 RCS file, deleting the existing
307 text.
308
309
310 The __-t__ option, in both its forms, has effect only
311 during an initial checkin; it is silently ignored
312 otherwise.
313
314
315 During the initial checkin, if __-t__ is not given,
316 __ci__ obtains the text from standard input, terminated
317 by end-of-file or by a line containing __.__ by itself.
318 The user is prompted for the text if interaction is
319 possible; see __-I__.
320
321
322 For backward compatibility with older versions of
323 RCS , a bare __-t__ option is
324 ignored.
325
326
327 __-T__
328
329
330 Set the RCS file's modification time to the
331 new revision's time if the former precedes the latter and
332 there is a new revision; preserve the RCS
333 file's modification time otherwise. If you have locked a
334 revision, __ci__ usually updates the RCS
335 file's modification time to the current time, because the
336 lock is stored in the RCS file and removing
337 the lock requires changing the RCS file. This
338 can create an RCS file newer than the working
339 file in one of two ways: first, __ci -M__ can create a
340 working file with a date before the current time; second,
341 when reverting to the previous revision the
342 RCS file can change while the working file
343 remains unchanged. These two cases can cause excessive
344 recompilation caused by a make(1) dependency of the
345 working file on the RCS file. The __-T__
346 option inhibits this recompilation by lying about the
347 RCS file's date. Use this option with care;
348 it can suppress recompilation even when a checkin of one
349 working file should affect another working file associated
350 with the same RCS file. For example, suppose
351 the RCS file's time is 01:00, the (changed)
352 working file's time is 02:00, some other copy of the working
353 file has a time of 03:00, and the current time is 04:00.
354 Then __ci -d -T__ sets the RCS file's time
355 to 02:00 instead of the usual 04:00; this causes
356 make(1) to think (incorrectly) that the other copy is
357 newer than the RCS file.
358
359
360 __-w__''login''
361
362
363 uses ''login'' for the author field of the deposited
364 revision. Useful for lying about the author, and for
365 __-k__ if no author is available.
366
367
368 __-V__
369
370
371 Print RCS 's version number.
372
373
374 __-V__''n''
375
376
377 Emulate RCS version ''n''. See
378 co(1) for details.
379
380
381 __-x__''suffixes''
382
383
384 specifies the suffixes for RCS files. A
385 nonempty suffix matches any pathname ending in the suffix.
386 An empty suffix matches any pathname of the form
387 __RCS/__''path'' or
388 ''path1''__/RCS/__''path2.'' The __-x__ option
389 can specify a list of suffixes separated by __/__. For
390 example, __-x,v/__ specifies two suffixes: __,v__ and
391 the empty suffix. If two or more suffixes are specified,
392 they are tried in order when looking for an
393 RCS file; the first one that works is used
394 for that file. If no RCS file is found but an
395 RCS file can be created, the suffixes are
396 tried in order to determine the new RCS
397 file's name. The default for ''suffixes'' is
398 installation-dependent; normally it is __,v/__ for hosts
399 like Unix that permit commas in filenames, and is empty
400 (i.e. just the empty suffix) for other hosts.
401
402
403 __-z__''zone''
404
405
406 specifies the date output format in keyword substitution,
407 and specifies the default time zone for ''date'' in the
408 __-d__''date'' option. The ''zone'' should be
409 empty, a numeric UTC offset, or the special
410 string __LT__ for local time. The default is an empty
411 ''zone'', which uses the traditional RCS
412 format of UTC without any time zone
413 indication and with slashes separating the parts of the
414 date; otherwise, times are output in ISO 8601
415 format with time zone indication. For example, if local time
416 is January 11, 1990, 8pm Pacific Standard Time, eight hours
417 west of UTC , then the time is output as
418 follows:
419
420
421 ''option time output
422 ''__-z 1990/01/12 04:00:00__ '' (default)
423 ''__-zLT 1990-01-11 20:00:00-08
424 -z+05:30 1990-01-12 09:30:00+05:30
425 __
426
427
428 The __-z__ option does not affect dates stored in
429 RCS files, which are always
430 UTC .
431 !!FILE NAMING
432
433
434 Pairs of RCS files and working files can be
435 specified in three ways (see also the example
436 section).
437
438
439 1) Both the RCS file and the working file are
440 given. The RCS pathname is of the form
441 ''path1''__/__''workfileX'' and the working
442 pathname is of the form ''path2''__/__''workfile''
443 where ''path1''__/__ and ''path2''__/__ are
444 (possibly different or empty) paths, ''workfile'' is a
445 filename, and ''X'' is an RCS suffix. If
446 ''X'' is empty, ''path1''__/__ must start with
447 __RCS/__ or must contain __/RCS/__.
448
449
450 2) Only the RCS file is given. Then the
451 working file is created in the current directory and its
452 name is derived from the name of the RCS file
453 by removing ''path1''__/__ and the suffix
454 ''X''.
455
456
457 3) Only the working file is given. Then __ci__ considers
458 each RCS suffix ''X'' in turn, looking for
459 an RCS file of the form
460 ''path2''__/RCS/__''workfileX'' or (if the former
461 is not found and ''X'' is nonempty)
462 ''path2''__/__''workfileX.''
463
464
465 If the RCS file is specified without a path
466 in 1) and 2), __ci__ looks for the RCS
467 file first in the directory __./RCS__ and then in the
468 current directory.
469
470
471 __ci__ reports an error if an attempt to open an
472 RCS file fails for an unusual reason, even if
473 the RCS file's pathname is just one of
474 several possibilities. For example, to suppress use of
475 RCS commands in a directory ''d'', create
476 a regular file named ''d''__/RCS__ so that casual
477 attempts to use RCS commands in ''d'' fail
478 because ''d''__/RCS__ is not a directory.
479 !!EXAMPLES
480
481
482 Suppose __,v__ is an RCS suffix and the
483 current directory contains a subdirectory __RCS__ with an
484 RCS file __io.c,v__. Then each of the
485 following commands check in a copy of __io.c__ into
486 __RCS/io.c,v__ as the latest revision, removing
487 __io.c__.
488
489
490 __ci io.c; ci RCS/io.c,v; ci io.c,v;
491 ci io.c RCS/io.c,v; ci io.c io.c,v;
492 ci RCS/io.c,v io.c; ci io.c,v io.c;
493 __
494
495
496 Suppose instead that the empty suffix is an
497 RCS suffix and the current directory contains
498 a subdirectory __RCS__ with an RCS file
499 __io.c__. The each of the following commands checks in a
500 new revision.
501
502
503 __ci io.c; ci RCS/io.c;
504 ci io.c RCS/io.c;
505 ci RCS/io.c io.c;
506 __
507 !!FILE MODES
508
509
510 An RCS file created by __ci__ inherits the
511 read and execute permissions from the working file. If the
512 RCS file exists already, __ci__ preserves
513 its read and execute permissions. __ci__ always turns off
514 all write permissions of RCS
515 files.
516 !!FILES
517
518
519 Temporary files are created in the directory containing the
520 working file, and also in the temporary directory (see
521 __TMPDIR__ under
522 __ENVIRONMENT__ ). A semaphore file or
523 files are created in the directory containing the
524 RCS file. With a nonempty suffix, the
525 semaphore names begin with the first character of the
526 suffix; therefore, do not specify an suffix whose first
527 character could be that of a working filename. With an empty
528 suffix, the semaphore names end with _____ so working
529 filenames should not end in _____.
530
531
532 __ci__ never changes an RCS or working
533 file. Normally, __ci__ unlinks the file and creates a new
534 one; but instead of breaking a chain of one or more symbolic
535 links to an RCS file, it unlinks the
536 destination file instead. Therefore, __ci__ breaks any
537 hard or symbolic links to any working file it changes; and
538 hard links to RCS files are ineffective, but
539 symbolic links to RCS files are
540 preserved.
541
542
543 The effective user must be able to search and write the
544 directory containing the RCS file. Normally,
545 the real user must be able to read the RCS
546 and working files and to search and write the directory
547 containing the working file; however, some older hosts
548 cannot easily switch between real and effective users, so on
549 these hosts the effective user is used for all accesses. The
550 effective user is the same as the real user unless your
551 copies of __ci__ and __co__ have setuid privileges. As
552 described in the next section, these privileges yield extra
553 security if the effective user owns all RCS
554 files and directories, and if only the effective user can
555 write RCS directories.
556
557
558 Users can control access to RCS files by
559 setting the permissions of the directory containing the
560 files; only users with write access to the directory can use
561 RCS commands to change its RCS
562 files. For example, in hosts that allow a user to belong to
563 several groups, one can make a group's RCS
564 directories writable to that group only. This approach
565 suffices for informal projects, but it means that any group
566 member can arbitrarily change the group's RCS
567 files, and can even remove them entirely. Hence more formal
568 projects sometimes distinguish between an RCS
569 administrator, who can change the RCS files
570 at will, and other project members, who can check in new
571 revisions but cannot otherwise change the RCS
572 files.
573 !!SETUID USE
574
575
576 To prevent anybody but their RCS
577 administrator from deleting revisions, a set of users can
578 employ setuid privileges as follows.
579
580
581 Check that the host supports RCS setuid use.
582 Consult a trustworthy expert if there are any doubts. It is
583 best if the __seteuid__ system call works as described in
584 Posix 1003.1a Draft 5, because RCS can switch
585 back and forth easily between real and effective users, even
586 if the real user is __root__. If not, the second best is
587 if the __setuid__ system call supports saved setuid (the
588 { _POSIX_SAVED_IDS } behavior of Posix
589 1003.1-1990); this fails only if the real or effective user
590 is __root__. If RCS detects any failure in
591 setuid, it quits immediately.
592
593
594 Choose a user ''A'' to serve as RCS
595 administrator for the set of users. Only ''A'' can invoke
596 the __rcs__ command on the users' RCS
597 files. ''A'' should not be __root__ or any other user
598 with special powers. Mutually suspicious sets of users
599 should use different administrators.
600
601
602 Choose a pathname ''B'' to be a directory of files to be
603 executed by the users.
604
605
606 Have ''A'' set up ''B'' to contain copies of __ci__
607 and __co__ that are setuid to ''A'' by copying the
608 commands from their standard installation directory ''D''
609 as follows:
610
611
612 __mkdir__ '' B
613 ''__cp__ '' D''__/c[[io]__ '' B
614 ''__chmod go-w,u+s__ '' B''__/c[[io]
615 __
616
617
618 Have each user prepend ''B'' to their path as
619 follows:
620
621
622 __PATH=__''B''__:$PATH; export PATH__ # ordinary shell
623 __set path=(__''B'' __ $path)__ # C shell
624
625
626 Have ''A'' create each RCS directory
627 ''R'' with write access only to ''A'' as
628 follows:
629
630
631 __mkdir__ '' R
632 ''__chmod go-w__ '' R
633 ''
634
635
636 If you want to let only certain users read the
637 RCS files, put the users into a group
638 ''G'', and have ''A'' further protect the
639 RCS directory as follows:
640
641
642 __chgrp__ '' G R
643 ''__chmod g-w,o-rwx__ '' R
644 ''
645
646
647 Have ''A'' copy old RCS files (if any)
648 into ''R'', to ensure that ''A'' owns
649 them.
650
651
652 An RCS file's access list limits who can
653 check in and lock revisions. The default access list is
654 empty, which grants checkin access to anyone who can read
655 the RCS file. If you want limit checkin
656 access, have ''A'' invoke __rcs -a__ on the file; see
657 rcs(1). In particular, __rcs -e -a__''A''
658 limits access to just ''A''.
659
660
661 Have ''A'' initialize any new RCS files
662 with __rcs -i__ before initial checkin, adding the
663 __-a__ option if you want to limit checkin
664 access.
665
666
667 Give setuid privileges only to __ci__, __co__, and
668 __rcsclean__; do not give them to __rcs__ or to any
669 other command.
670
671
672 Do not use other setuid commands to invoke
673 RCS commands; setuid is trickier than you
674 think!
675 !!ENVIRONMENT
676
677
678 __RCSINIT__
679
680
681 options prepended to the argument list, separated by spaces.
682 A backslash escapes spaces within an option. The
683 __RCSINIT__ options are prepended to the
684 argument lists of most RCS commands. Useful
685 __RCSINIT__ options include __-q__,
686 __-V__, __-x__, and __-z__.
687
688
689 __TMPDIR__
690
691
692 Name of the temporary directory. If not set, the environment
693 variables __TMP__ and
694 __TEMP__ are inspected instead and the
695 first value found is taken; if none of them are set, a
696 host-dependent default is used, typically
697 __/tmp__.
698 !!DIAGNOSTICS
699
700
701 For each revision, __ci__ prints the RCS
702 file, the working file, and the number of both the deposited
703 and the preceding revision. The exit status is zero if and
704 only if all operations were successful.
705 !!IDENTIFICATION
706
707
708 Author: Walter F. Tichy.
709 Manual Page Revision: 5.17; Release Date: 1995/06/16.
710 Copyright 1982, 1988, 1989 Walter F. Tichy.
711 Copyright 1990, 1991, 1992, 1993, 1994, 1995 Paul
712 Eggert.
713 !!SEE ALSO
714
715
716 co(1), emacs(1), ident(1), make(1), rcs(1), rcsclean(1),
717 rcsdiff(1), rcsintro(1), rcsmerge(1), rlog(1), setuid(2),
718 rcsfile(5)
719 Walter F. Tichy, RCS --A System for Version
720 Control, ''Software--Practice ''
721 __15__, 7 (July 1985), 637-654.
722 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.