5 .Id $FreeBSD: src/gnu/usr.bin/rcs/ci/ci.1,v 1.6 1999/08/27 23:36:38 peter Exp $
6 .Id $DragonFly: src/gnu/usr.bin/rcs/ci/ci.1,v 1.2 2003/06/17 04:25:47 dillon Exp $
14 ci \- check in RCS revisions
17 .RI [ options ] " file " .\|.\|.
20 stores new revisions into \*r files.
21 Each pathname matching an \*r suffix
22 is taken to be an \*r file.
24 are assumed to be working files containing new revisions.
26 deposits the contents of each working file
27 into the corresponding \*r file.
28 If only a working file is given,
30 tries to find the corresponding \*r file in an \*r subdirectory
31 and then in the working file's directory.
38 to work, the caller's login must be on the access list,
39 except if the access list is empty or the caller is the superuser or the
41 To append a new revision to an existing branch, the tip revision on
42 that branch must be locked by the caller. Otherwise, only a
43 new branch can be created. This restriction is not enforced
44 for the owner of the file if non-strict locking is used
47 A lock held by someone else can be broken with the
55 checks whether the revision to be deposited differs from the preceding one.
56 If not, instead of creating a new revision
58 reverts to the preceding one.
61 removes the working file and any lock;
65 removes any lock, and then they both generate a new working file much as if
69 had been applied to the preceding revision.
74 options apply to the preceding revision.
76 For each revision deposited,
78 prompts for a log message.
79 The log message should summarize the change and must be terminated by
80 end-of-file or by a line containing
83 If several files are checked in
85 asks whether to reuse the
87 If the standard input is not a terminal,
90 and uses the same log message for all files.
94 If the \*r file does not exist,
97 deposits the contents of the working file as the initial revision
100 The access list is initialized to empty.
101 Instead of the log message,
103 requests descriptive text (see
109 of the deposited revision can be given by any of the options
122 can be symbolic, numeric, or mixed.
125 must already be defined;
130 options for assigning names during checkin.
136 determines the revision number from keyword values in the working file.
140 begins with a period,
141 then the default branch (normally the trunk) is prepended to it.
144 is a branch number followed by a period,
145 then the latest revision on that branch is used.
149 is a revision number, it must be higher than the latest
150 one on the branch to which
152 belongs, or must start a new branch.
156 is a branch rather than a revision number,
157 the new revision is appended to that branch. The level number is obtained
158 by incrementing the tip revision number of that branch.
161 indicates a non-existing branch,
162 that branch is created with the initial revision numbered
171 tries to derive the new revision number from
172 the caller's last lock. If the caller has locked the tip revision of a branch,
173 the new revision is appended to that branch.
174 The new revision number is obtained
175 by incrementing the tip revision number.
176 If the caller locked a non-tip revision, a new branch is started at
177 that revision by incrementing the highest branch number at that revision.
178 The default initial branch and level numbers are
183 is omitted and the caller has no lock, but owns
187 then the revision is appended to the
188 default branch (normally the trunk; see the
193 Exception: On the trunk, revisions can be appended to the end, but
204 option (without any revision) has an unusual meaning in
206 With other \*r commands, a bare
208 option specifies the most recent revision on the default branch,
213 option reestablishes the default behavior of releasing a lock and
214 removing the working file, and is used to override any default
218 options established by shell aliases or scripts.
223 except it performs an additional
226 deposited revision. Thus, the deposited revision is immediately
227 checked out again and locked.
228 This is useful for saving a revision although one wants to continue
229 editing it after the checkin.
234 except that the deposited revision is not locked.
235 This lets one read the working file
236 immediately after checkin.
245 options are mutually exclusive and silently override each other.
257 forces a deposit; the new revision is deposited even it is not different
258 from the preceding one.
261 searches the working file for keyword values to determine its revision number,
262 creation date, state, and author (see
265 values to the deposited revision, rather than computing them locally.
266 It also generates a default login message noting the login of the caller
267 and the actual checkin date.
268 This option is useful for software distribution. A revision that is sent to
269 several sites should be checked in with the
271 option at these sites to
272 preserve the original number, date, author, and state.
273 The extracted keyword values and the default log message can be overridden
279 and any option that carries a revision number.
282 quiet mode; diagnostic output is not printed.
283 A revision that is not different from the preceding one is not deposited,
289 initial checkin; report an error if the \*r file already exists.
290 This avoids race conditions in certain applications.
293 just checkin and do not initialize;
294 report an error if the \*r file does not already exist.
298 the user is prompted and questioned
299 even if the standard input is not a terminal.
301 .BR \-d "[\f2date\fP]"
304 for the checkin date and time.
307 is specified in free format as explained in
309 This is useful for lying about the checkin date, and for
311 if no date is available.
314 is empty, the working file's time of last modification is used.
317 Set the modification time on any new working file
318 to be the date of the retrieved revision.
320 .BI "ci\ \-d\ \-M\ \-u" "\ f"
323 modification time, even if
325 contents change due to keyword substitution.
326 Use this option with care; it can confuse
332 as the log message for all revisions checked in.
333 By convention, log messages that start with
335 are comments and are ignored by programs like GNU Emacs's
338 Also, log messages that start with
340 (followed by white space) are meant to be clumped together if possible,
341 even if they are associated with different files; the
343 label is used only for clumping,
344 and is not considered to be part of the log message itself.
347 assigns the symbolic name
349 to the number of the checked-in revision.
351 prints an error message if
353 is already assigned to another
359 except that it overrides a previous assignment of
363 sets the state of the checked-in revision to the identifier
369 writes descriptive text from the contents of the named
372 deleting the existing text.
379 Write descriptive text from the
381 into the \*r file, deleting the existing text.
386 option, in both its forms, has effect only during an initial checkin;
387 it is silently ignored otherwise.
389 During the initial checkin, if
393 obtains the text from standard input,
394 terminated by end-of-file or by a line containing
397 The user is prompted for the text if interaction is possible; see
400 For backward compatibility with older versions of \*r, a bare
406 Set the \*r file's modification time to the new revision's time
407 if the former precedes the latter and there is a new revision;
408 preserve the \*r file's modification time otherwise.
409 If you have locked a revision,
411 usually updates the \*r file's modification time to the current time,
412 because the lock is stored in the \*r file
413 and removing the lock requires changing the \*r file.
414 This can create an \*r file newer than the working file in one of two ways:
417 can create a working file with a date before the current time;
418 second, when reverting to the previous revision
419 the \*r file can change while the working file remains unchanged.
420 These two cases can cause excessive recompilation caused by a
422 dependency of the working file on the \*r file.
425 option inhibits this recompilation by lying about the \*r file's date.
426 Use this option with care; it can suppress recompilation even when
427 a checkin of one working file should affect
428 another working file associated with the same \*r file.
429 For example, suppose the \*r file's time is 01:00,
430 the (changed) working file's time is 02:00,
431 some other copy of the working file has a time of 03:00,
432 and the current time is 04:00.
435 sets the \*r file's time to 02:00 instead of the usual 04:00;
438 to think (incorrectly) that the other copy is newer than the \*r file.
443 for the author field of the deposited revision.
444 Useful for lying about the author, and for
446 if no author is available.
449 Print \*r's version number.
459 specifies the suffixes for \*r files.
460 A nonempty suffix matches any pathname ending in the suffix.
461 An empty suffix matches any pathname of the form
464 .IB path1 /RCS/ path2.
467 option can specify a list of suffixes
472 specifies two suffixes:
474 and the empty suffix.
475 If two or more suffixes are specified,
476 they are tried in order when looking for an \*r file;
477 the first one that works is used for that file.
478 If no \*r file is found but an \*r file can be created,
479 the suffixes are tried in order
480 to determine the new \*r file's name.
483 is installation-dependent; normally it is
485 for hosts like Unix that permit commas in filenames,
486 and is empty (i.e. just the empty suffix) for other hosts.
489 specifies the date output format in keyword substitution,
490 and specifies the default time zone for
497 should be empty, a numeric \*u offset, or the special string
500 The default is an empty
502 which uses the traditional \*r format of \*u without any time zone indication
503 and with slashes separating the parts of the date;
504 otherwise, times are output in \*i 8601 format with time zone indication.
505 For example, if local time is January 11, 1990, 8pm Pacific Standard Time,
506 eight hours west of \*u,
507 then the time is output as follows:
512 .ta \w'\f3\-z+05:30\fP 'u +\w'\f31990-01-11 09:30:00+05:30\fP 'u
514 \f2option\fP \f2time output\fP
515 \f3\-z\fP \f31990/01/12 04:00:00\fP \f2(default)\fP
516 \f3\-zLT\fP \f31990-01-11 20:00:00\-08\fP
517 \f3\-z+05:30\fP \f31990-01-12 09:30:00+05:30\fP
524 option does not affect dates stored in \*r files,
525 which are always \*u.
527 Pairs of \*r files and working files can be specified in three ways
531 1) Both the \*r file and the working file are given. The \*r pathname is of
533 .IB path1 / workfileX
534 and the working pathname is of the form
540 are (possibly different or empty) paths,
554 2) Only the \*r file is given. Then the working file is created in the current
555 directory and its name is derived from the name of the \*r file
561 3) Only the working file is given.
564 considers each \*r suffix
566 in turn, looking for an \*r file of the form
567 .IB path2 /RCS/ workfileX
568 or (if the former is not found and
571 .IB path2 / workfileX.
573 If the \*r file is specified without a path in 1) and 2),
575 looks for the \*r file first in the directory
577 and then in the current
581 reports an error if an attempt to open an \*r file fails for an unusual reason,
582 even if the \*r file's pathname is just one of several possibilities.
583 For example, to suppress use of \*r commands in a directory
585 create a regular file named
587 so that casual attempts to use \*r commands in
595 is an \*r suffix and the current directory contains a subdirectory
599 Then each of the following commands check in a copy of
603 as the latest revision, removing
609 ci io.c; ci RCS/io.c,v; ci io.c,v;
610 ci io.c RCS/io.c,v; ci io.c io.c,v;
611 ci RCS/io.c,v io.c; ci io.c,v io.c;
616 Suppose instead that the empty suffix
617 is an \*r suffix and the current directory contains a subdirectory
621 The each of the following commands checks in a new revision.
626 ci io.c; ci RCS/io.c;
633 An \*r file created by
635 inherits the read and execute permissions
636 from the working file. If the \*r file exists already,
638 preserves its read and execute permissions.
640 always turns off all write permissions of \*r files.
642 Temporary files are created in the directory containing
643 the working file, and also in the temporary directory (see
646 .BR \s-1ENVIRONMENT\s0 ).
647 A semaphore file or files are created in the directory containing the \*r file.
648 With a nonempty suffix, the semaphore names begin with
649 the first character of the suffix; therefore, do not specify an suffix
650 whose first character could be that of a working filename.
651 With an empty suffix, the semaphore names end with
653 so working filenames should not end in
657 never changes an \*r or working file.
660 unlinks the file and creates a new one;
661 but instead of breaking a chain of one or more symbolic links to an \*r file,
662 it unlinks the destination file instead.
665 breaks any hard or symbolic links to any working file it changes;
666 and hard links to \*r files are ineffective,
667 but symbolic links to \*r files are preserved.
669 The effective user must be able to
670 search and write the directory containing the \*r file.
671 Normally, the real user must be able to
672 read the \*r and working files
673 and to search and write the directory containing the working file;
674 however, some older hosts
675 cannot easily switch between real and effective users,
676 so on these hosts the effective user is used for all accesses.
677 The effective user is the same as the real user
678 unless your copies of
682 have setuid privileges.
683 As described in the next section,
684 these privileges yield extra security if
685 the effective user owns all \*r files and directories,
686 and if only the effective user can write \*r directories.
688 Users can control access to \*r files by setting the permissions
689 of the directory containing the files; only users with write access
690 to the directory can use \*r commands to change its \*r files.
691 For example, in hosts that allow a user to belong to several groups,
692 one can make a group's \*r directories writable to that group only.
693 This approach suffices for informal projects,
694 but it means that any group member can arbitrarily change the group's \*r files,
695 and can even remove them entirely.
696 Hence more formal projects sometimes distinguish between an \*r administrator,
697 who can change the \*r files at will, and other project members,
698 who can check in new revisions but cannot otherwise change the \*r files.
700 To prevent anybody but their \*r administrator from deleting revisions,
701 a set of users can employ setuid privileges as follows.
702 .nr n \w'\(bu'+2n-1/1n
704 .if \n(.g .if r an-tag-sep .ds n \w'\(bu'u+\n[an-tag-sep]u
706 Check that the host supports \*r setuid use.
707 Consult a trustworthy expert if there are any doubts.
710 system call works as described in Posix 1003.1a Draft 5,
711 because \*r can switch back and forth easily
712 between real and effective users, even if the real user is
714 If not, the second best is if the
716 system call supports saved setuid
717 (the {\s-1_POSIX_SAVED_IDS\s0} behavior of Posix 1003.1-1990);
718 this fails only if the real or effective user is
720 If \*r detects any failure in setuid, it quits immediately.
724 to serve as \*r administrator for the set of users.
729 command on the users' \*r files.
733 or any other user with special powers.
734 Mutually suspicious sets of users should use different administrators.
738 to be a directory of files to be executed by the users.
750 by copying the commands from their standard installation directory
758 \f3cp\fP \f2D\fP\^\f3/c[io]\fP \f2B\fP
759 \f3chmod go\-w,u+s\fP \f2B\fP\f3/c[io]\fP
763 Have each user prepend
765 to their path as follows:
770 \f3PATH=\fP\f2B\fP\f3:$PATH; export PATH\fP # ordinary shell
771 \f3set path=(\fP\f2B\fP \f3$path)\fP # C shell
777 create each \*r directory
779 with write access only to
787 \f3chmod go\-w\fP \f2R\fP
791 If you want to let only certain users read the \*r files,
792 put the users into a group
796 further protect the \*r directory as follows:
801 \f3chgrp\fP \f2G R\fP
802 \f3chmod g\-w,o\-rwx\fP \f2R\fP
808 copy old \*r files (if any) into
814 An \*r file's access list limits who can check in and lock revisions.
815 The default access list is empty,
816 which grants checkin access to anyone who can read the \*r file.
817 If you want limit checkin access,
825 .BI "rcs\ \-e\ \-a" A
826 limits access to just
831 initialize any new \*r files with
833 before initial checkin, adding the
835 option if you want to limit checkin access.
837 Give setuid privileges only to
844 or to any other command.
846 Do not use other setuid commands to invoke \*r commands;
847 setuid is trickier than you think!
851 options prepended to the argument list, separated by spaces.
852 A backslash escapes spaces within an option.
855 options are prepended to the argument lists of most \*r commands.
866 Name of the temporary directory.
867 If not set, the environment variables
871 are inspected instead and the first value found is taken;
872 if none of them are set,
873 a host-dependent default is used, typically
878 prints the \*r file, the working file, and the number
879 of both the deposited and the preceding revision.
880 The exit status is zero if and only if all operations were successful.
882 Author: Walter F. Tichy.
884 Manual Page Revision: \*(Rv; Release Date: \*(Dt.
886 Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
888 Copyright \(co 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert.
891 ident(1), make(1), rcs(1), rcsclean(1), rcsdiff(1),
892 rcsintro(1), rcsmerge(1), rlog(1), setuid(2), rcsfile(5)
895 \*r\*-A System for Version Control,
896 .I "Software\*-Practice & Experience"
898 7 (July 1985), 637-654.
projects / dragonfly.git / blob