1.de Id
2.ds Rv \\$3
3.ds Dt \\$4
4..
5.Id $Id: ci.1,v 5.9 1991/10/07 17:32:46 eggert Exp $
6.ds r \&\s-1RCS\s0
7.if n .ds - \%--
8.if t .ds - \(em
9.TH CI 1 \*(Dt GNU
10.SH NAME
11ci \- check in RCS revisions
12.SH SYNOPSIS
13.B ci
14.RI [ options ] " file " .\|.\|.
--- 21 unchanged lines hidden (view full) ---
36except if the access list is empty or the caller is the superuser or the
37owner of the file.
38To append a new revision to an existing branch, the tip revision on
39that branch must be locked by the caller. Otherwise, only a
40new branch can be created. This restriction is not enforced
41for the owner of the file if non-strict locking is used
42(see
43.BR rcs (1)).
44A lock held by someone else may be broken with the
45.B rcs
46command.
47.PP
48Unless the
49.B \-f
50option is given,
51.B ci
52checks whether the revision to be deposited differs from the preceding one.
--- 47 unchanged lines hidden (view full) ---
100requests descriptive text (see
101.B \-t
102below).
103.PP
104The number
105.I rev
106of the deposited revision can be given by any of the options
107.BR \-f ,
108.BR \-I ,
109.BR \-k ,
110.BR \-l ,
111.BR \-M ,
112.BR \-q ,
113.BR \-r ,
114or
115.BR \-u .
116.I rev
117may be symbolic, numeric, or mixed.
118If
119.I rev
120is
121.BR $ ,
122.B ci
123determines the revision number from keyword values in the working file.
124.PP
125If
126.I rev
127is a revision number, it must be higher than the latest
128one on the branch to which
129.I rev
130belongs, or must start a new branch.
131.PP
132If
133.I rev
134is a branch rather than a revision number,
--- 32 unchanged lines hidden (view full) ---
167.B \-b
168option of
169.BR rcs (1)).
170.PP
171Exception: On the trunk, revisions can be appended to the end, but
172not inserted.
173.SH OPTIONS
174.TP
175.BR \-r [\f2rev\fP]
176checks in a revision, releases the corresponding lock, and
177removes the working file. This is the default.
178.RS
179.PP
180The
181.B \-r
182option has an unusual meaning in
183.BR ci .
184In other \*r commands,
185.B \-r
186merely specifies a revision number,
187but in
188.B ci
189it also releases a lock and removes the working file.
190See
191.B \-u
192for a tricky example.
193.RE
194.TP
195.BR \-l [\f2rev\fP]
196works like
197.BR \-r ,
198except it performs an additional
199.B "co\ \-l"
200for the
201deposited revision. Thus, the deposited revision is immediately
--- 6 unchanged lines hidden (view full) ---
208.BR \-l ,
209except that the deposited revision is not locked.
210This lets one read the working file
211immediately after checkin.
212.RS
213.PP
214The
215.BR \-l ,
216.BR \-r ,
217and
218.B \-u
219options are mutually exclusive and silently override each other.
220For example,
221.B "ci\ \-u\ \-r"
222is equivalent to
223.B "ci\ \-r"
224because
225.B \-r
226overrides
227.BR \-u .
228.RE
229.TP
230.BR \-f [\f2rev\fP]
231forces a deposit; the new revision is deposited even it is not different
232from the preceding one.
--- 6 unchanged lines hidden (view full) ---
239values to the deposited revision, rather than computing them locally.
240It also generates a default login message noting the login of the caller
241and the actual checkin date.
242This option is useful for software distribution. A revision that is sent to
243several sites should be checked in with the
244.B \-k
245option at these sites to
246preserve the original number, date, author, and state.
247The extracted keyword values and the default log message may be overridden
248with the options
249.BR \-d ,
250.BR \-m ,
251.BR \-s ,
252.BR \-w ,
253and any option that carries a revision number.
254.TP
255.BR \-q [\f2rev\fP]
256quiet mode; diagnostic output is not printed.
257A revision that is not different from the preceding one is not deposited,
258unless
259.B \-f
260is given.
261.TP
262.BR \-I [\f2rev\fP]
263interactive mode;
264the user is prompted and questioned
265even if the standard input is not a terminal.
266.TP
267.BR \-d "[\f2date\fP]"
268uses
269.I date
--- 21 unchanged lines hidden (view full) ---
291contents change due to keyword substitution.
292Use this option with care; it can confuse
293.BR make (1).
294.TP
295.BI \-m "msg"
296uses the string
297.I msg
298as the log message for all revisions checked in.
299.TP
300.BI \-n "name"
301assigns the symbolic name
302.I name
303to the number of the checked-in revision.
304.B ci
305prints an error message if
306.I name
--- 14 unchanged lines hidden (view full) ---
321.TP
322.BI \-t file
323writes descriptive text from the contents of the named
324.I file
325into the \*r file,
326deleting the existing text.
327The
328.I file
329may not begin with
330.BR \- .
331.TP
332.BI \-t\- string
333Write descriptive text from the
334.I string
335into the \*r file, deleting the existing text.
336.RS
337.PP
--- 13 unchanged lines hidden (view full) ---
351The user is prompted for the text if interaction is possible; see
352.BR \-I .
353.PP
354For backward compatibility with older versions of \*r, a bare
355.B \-t
356option is ignored.
357.RE
358.TP
359.BI \-w "login"
360uses
361.I login
362for the author field of the deposited revision.
363Useful for lying about the author, and for
364.B \-k
365if no author is available.
366.TP
367.BI \-V n
368Emulate \*r version
369.IR n .
370See
371.BR co (1)
372for details.
373.TP
374.BI \-x "suffixes"
375specifies the suffixes for \*r files.
376A nonempty suffix matches any pathname ending in the suffix.
377An empty suffix matches any pathname of the form
378.BI RCS/ file
379or
380.IB path /RCS/ file.
381The
382.B \-x
383option can specify a list of suffixes
384separated by
385.BR / .
386For example,
387.B \-x,v/
388specifies two suffixes:
--- 4 unchanged lines hidden (view full) ---
393the first one that works is used for that file.
394If no \*r file is found but an \*r file can be created,
395the suffixes are tried in order
396to determine the new \*r file's name.
397The default for
398.IR suffixes
399is installation-dependent; normally it is
400.B ,v/
401for hosts like Unix that permit commas in file names,
402and is empty (i.e. just the empty suffix) for other hosts.
403.SH "FILE NAMING"
404Pairs of \*r files and working files may be specified in three ways
405(see also the
406example section).
407.PP
4081) Both the \*r file and the working file are given. The \*r pathname is of
409the form
410.IB path1 / workfileX
411and the working pathname is of the form
412.IB path2 / workfile
--- 5 unchanged lines hidden (view full) ---
418.I workfile
419is a filename, and
420.I X
421is an \*r suffix.
422If
423.I X
424is empty,
425.IB path1 /
426must be
427.B RCS/
428or must end in
429.BR /RCS/ .
430.PP
4312) Only the \*r file is given. Then the working file is created in the current
432directory and its name is derived from the name of the \*r file
433by removing
434.IB path1 /
435and the suffix
436.IR X .
--- 74 unchanged lines hidden (view full) ---
511.B ci
512inherits the read and execute permissions
513from the working file. If the \*r file exists already,
514.B ci
515preserves its read and execute permissions.
516.B ci
517always turns off all write permissions of \*r files.
518.SH FILES
519Several temporary files may be created in the directory containing
520the working file, and also in the temporary directory (see
521.B \s-1TMPDIR\s0
522under
523.BR \s-1ENVIRONMENT\s0 ).
524A semaphore file or files are created in the directory containing the \*r file.
525With a nonempty suffix, the semaphore names begin with
526the first character of the suffix; therefore, do not specify an suffix
527whose first character could be that of a working filename.
--- 43 unchanged lines hidden (view full) ---
571but it means that any group member can arbitrarily change the group's \*r files,
572and can even remove them entirely.
573Hence more formal projects sometimes distinguish between an \*r administrator,
574who can change the \*r files at will, and other project members,
575who can check in new revisions but cannot otherwise change the \*r files.
576.SH "SETUID USE"
577To prevent anybody but their \*r administrator from deleting revisions,
578a set of users can employ setuid privileges as follows.
579.nr n \w'\(bu '+1n-1/1n
580.IP \(bu \nn
581Check that the host supports \*r setuid use.
582Consult a trustworthy expert if there are any doubts.
583It is best if the
584.B seteuid()
585system call works as described in Posix 1003.1a Draft 5,
586because \*r can switch back and forth easily
587between real and effective users, even if the real user is
588.BR root .
589If not, the second best is if the
590.B setuid()
591system call supports saved setuid
592(the {\s-1_POSIX_SAVED_IDS\s0} behavior of Posix 1003.1-1990);
593this fails only if the real user is
594.BR root .
595If \*r detects any failure in setuid, it quits immediately.
596.IP \(bu \nn
597Choose a user
598.I A
599to serve as \*r administrator for the set of users.
600Only
601.I A
602will be able to invoke the
603.B rcs
604command on the users' \*r files.
605.I A
606should not be
607.B root
608or any other user with special powers.
609Mutually suspicious sets of users should use different administrators.
610.IP \(bu \nn
611Choose a path name
612.I B
613that will be a directory of files to be executed by the users.
614.IP \(bu \nn
615Have
616.I A
617set up
618.I B
619to contain copies of
620.B ci
621and
--- 106 unchanged lines hidden (view full) ---
728The
729.B \s-1RCSINIT\s0
730options are prepended to the argument lists of most \*r commands.
731Useful
732.B \s-1RCSINIT\s0
733options include
734.BR \-q ,
735.BR \-V ,
736and
737.BR \-x .
738.TP
739.B \s-1TMPDIR\s0
740Name of the temporary directory.
741If not set, the environment variables
742.B \s-1TMP\s0
743and
744.B \s-1TEMP\s0
745are inspected instead and the first value found is taken;
--- 4 unchanged lines hidden (view full) ---
750For each revision,
751.B ci
752prints the \*r file, the working file, and the number
753of both the deposited and the preceding revision.
754The exit status is zero if and only if all operations were successful.
755.SH IDENTIFICATION
756Author: Walter F. Tichy.
757.br
758Revision Number: \*(Rv; Release Date: \*(Dt.
759.br
760Copyright \(co 1982, 1988, 1989 by Walter F. Tichy.
761.br
762Copyright \(co 1990, 1991 by Paul Eggert.
763.SH "SEE ALSO"
764co(1), ident(1), make(1), rcs(1), rcsclean(1), rcsdiff(1),
765rcsintro(1), rcsmerge(1), rlog(1), rcsfile(5)
766.br
767Walter F. Tichy,
768\*r\*-A System for Version Control,
769.I "Software\*-Practice & Experience"
770.BR 15 ,
7717 (July 1985), 637-654.
772.br
2.ds Rv \\$3
3.ds Dt \\$4
4..
5.Id $Id: ci.1,v 5.9 1991/10/07 17:32:46 eggert Exp $
6.ds r \&\s-1RCS\s0
7.if n .ds - \%--
8.if t .ds - \(em
9.TH CI 1 \*(Dt GNU
10.SH NAME
11ci \- check in RCS revisions
12.SH SYNOPSIS
13.B ci
14.RI [ options ] " file " .\|.\|.
--- 21 unchanged lines hidden (view full) ---
36except if the access list is empty or the caller is the superuser or the
37owner of the file.
38To append a new revision to an existing branch, the tip revision on
39that branch must be locked by the caller. Otherwise, only a
40new branch can be created. This restriction is not enforced
41for the owner of the file if non-strict locking is used
42(see
43.BR rcs (1)).
44A lock held by someone else may be broken with the
45.B rcs
46command.
47.PP
48Unless the
49.B \-f
50option is given,
51.B ci
52checks whether the revision to be deposited differs from the preceding one.
--- 47 unchanged lines hidden (view full) ---
100requests descriptive text (see
101.B \-t
102below).
103.PP
104The number
105.I rev
106of the deposited revision can be given by any of the options
107.BR \-f ,
108.BR \-I ,
109.BR \-k ,
110.BR \-l ,
111.BR \-M ,
112.BR \-q ,
113.BR \-r ,
114or
115.BR \-u .
116.I rev
117may be symbolic, numeric, or mixed.
118If
119.I rev
120is
121.BR $ ,
122.B ci
123determines the revision number from keyword values in the working file.
124.PP
125If
126.I rev
127is a revision number, it must be higher than the latest
128one on the branch to which
129.I rev
130belongs, or must start a new branch.
131.PP
132If
133.I rev
134is a branch rather than a revision number,
--- 32 unchanged lines hidden (view full) ---
167.B \-b
168option of
169.BR rcs (1)).
170.PP
171Exception: On the trunk, revisions can be appended to the end, but
172not inserted.
173.SH OPTIONS
174.TP
175.BR \-r [\f2rev\fP]
176checks in a revision, releases the corresponding lock, and
177removes the working file. This is the default.
178.RS
179.PP
180The
181.B \-r
182option has an unusual meaning in
183.BR ci .
184In other \*r commands,
185.B \-r
186merely specifies a revision number,
187but in
188.B ci
189it also releases a lock and removes the working file.
190See
191.B \-u
192for a tricky example.
193.RE
194.TP
195.BR \-l [\f2rev\fP]
196works like
197.BR \-r ,
198except it performs an additional
199.B "co\ \-l"
200for the
201deposited revision. Thus, the deposited revision is immediately
--- 6 unchanged lines hidden (view full) ---
208.BR \-l ,
209except that the deposited revision is not locked.
210This lets one read the working file
211immediately after checkin.
212.RS
213.PP
214The
215.BR \-l ,
216.BR \-r ,
217and
218.B \-u
219options are mutually exclusive and silently override each other.
220For example,
221.B "ci\ \-u\ \-r"
222is equivalent to
223.B "ci\ \-r"
224because
225.B \-r
226overrides
227.BR \-u .
228.RE
229.TP
230.BR \-f [\f2rev\fP]
231forces a deposit; the new revision is deposited even it is not different
232from the preceding one.
--- 6 unchanged lines hidden (view full) ---
239values to the deposited revision, rather than computing them locally.
240It also generates a default login message noting the login of the caller
241and the actual checkin date.
242This option is useful for software distribution. A revision that is sent to
243several sites should be checked in with the
244.B \-k
245option at these sites to
246preserve the original number, date, author, and state.
247The extracted keyword values and the default log message may be overridden
248with the options
249.BR \-d ,
250.BR \-m ,
251.BR \-s ,
252.BR \-w ,
253and any option that carries a revision number.
254.TP
255.BR \-q [\f2rev\fP]
256quiet mode; diagnostic output is not printed.
257A revision that is not different from the preceding one is not deposited,
258unless
259.B \-f
260is given.
261.TP
262.BR \-I [\f2rev\fP]
263interactive mode;
264the user is prompted and questioned
265even if the standard input is not a terminal.
266.TP
267.BR \-d "[\f2date\fP]"
268uses
269.I date
--- 21 unchanged lines hidden (view full) ---
291contents change due to keyword substitution.
292Use this option with care; it can confuse
293.BR make (1).
294.TP
295.BI \-m "msg"
296uses the string
297.I msg
298as the log message for all revisions checked in.
299.TP
300.BI \-n "name"
301assigns the symbolic name
302.I name
303to the number of the checked-in revision.
304.B ci
305prints an error message if
306.I name
--- 14 unchanged lines hidden (view full) ---
321.TP
322.BI \-t file
323writes descriptive text from the contents of the named
324.I file
325into the \*r file,
326deleting the existing text.
327The
328.I file
329may not begin with
330.BR \- .
331.TP
332.BI \-t\- string
333Write descriptive text from the
334.I string
335into the \*r file, deleting the existing text.
336.RS
337.PP
--- 13 unchanged lines hidden (view full) ---
351The user is prompted for the text if interaction is possible; see
352.BR \-I .
353.PP
354For backward compatibility with older versions of \*r, a bare
355.B \-t
356option is ignored.
357.RE
358.TP
359.BI \-w "login"
360uses
361.I login
362for the author field of the deposited revision.
363Useful for lying about the author, and for
364.B \-k
365if no author is available.
366.TP
367.BI \-V n
368Emulate \*r version
369.IR n .
370See
371.BR co (1)
372for details.
373.TP
374.BI \-x "suffixes"
375specifies the suffixes for \*r files.
376A nonempty suffix matches any pathname ending in the suffix.
377An empty suffix matches any pathname of the form
378.BI RCS/ file
379or
380.IB path /RCS/ file.
381The
382.B \-x
383option can specify a list of suffixes
384separated by
385.BR / .
386For example,
387.B \-x,v/
388specifies two suffixes:
--- 4 unchanged lines hidden (view full) ---
393the first one that works is used for that file.
394If no \*r file is found but an \*r file can be created,
395the suffixes are tried in order
396to determine the new \*r file's name.
397The default for
398.IR suffixes
399is installation-dependent; normally it is
400.B ,v/
401for hosts like Unix that permit commas in file names,
402and is empty (i.e. just the empty suffix) for other hosts.
403.SH "FILE NAMING"
404Pairs of \*r files and working files may be specified in three ways
405(see also the
406example section).
407.PP
4081) Both the \*r file and the working file are given. The \*r pathname is of
409the form
410.IB path1 / workfileX
411and the working pathname is of the form
412.IB path2 / workfile
--- 5 unchanged lines hidden (view full) ---
418.I workfile
419is a filename, and
420.I X
421is an \*r suffix.
422If
423.I X
424is empty,
425.IB path1 /
426must be
427.B RCS/
428or must end in
429.BR /RCS/ .
430.PP
4312) Only the \*r file is given. Then the working file is created in the current
432directory and its name is derived from the name of the \*r file
433by removing
434.IB path1 /
435and the suffix
436.IR X .
--- 74 unchanged lines hidden (view full) ---
511.B ci
512inherits the read and execute permissions
513from the working file. If the \*r file exists already,
514.B ci
515preserves its read and execute permissions.
516.B ci
517always turns off all write permissions of \*r files.
518.SH FILES
519Several temporary files may be created in the directory containing
520the working file, and also in the temporary directory (see
521.B \s-1TMPDIR\s0
522under
523.BR \s-1ENVIRONMENT\s0 ).
524A semaphore file or files are created in the directory containing the \*r file.
525With a nonempty suffix, the semaphore names begin with
526the first character of the suffix; therefore, do not specify an suffix
527whose first character could be that of a working filename.
--- 43 unchanged lines hidden (view full) ---
571but it means that any group member can arbitrarily change the group's \*r files,
572and can even remove them entirely.
573Hence more formal projects sometimes distinguish between an \*r administrator,
574who can change the \*r files at will, and other project members,
575who can check in new revisions but cannot otherwise change the \*r files.
576.SH "SETUID USE"
577To prevent anybody but their \*r administrator from deleting revisions,
578a set of users can employ setuid privileges as follows.
579.nr n \w'\(bu '+1n-1/1n
580.IP \(bu \nn
581Check that the host supports \*r setuid use.
582Consult a trustworthy expert if there are any doubts.
583It is best if the
584.B seteuid()
585system call works as described in Posix 1003.1a Draft 5,
586because \*r can switch back and forth easily
587between real and effective users, even if the real user is
588.BR root .
589If not, the second best is if the
590.B setuid()
591system call supports saved setuid
592(the {\s-1_POSIX_SAVED_IDS\s0} behavior of Posix 1003.1-1990);
593this fails only if the real user is
594.BR root .
595If \*r detects any failure in setuid, it quits immediately.
596.IP \(bu \nn
597Choose a user
598.I A
599to serve as \*r administrator for the set of users.
600Only
601.I A
602will be able to invoke the
603.B rcs
604command on the users' \*r files.
605.I A
606should not be
607.B root
608or any other user with special powers.
609Mutually suspicious sets of users should use different administrators.
610.IP \(bu \nn
611Choose a path name
612.I B
613that will be a directory of files to be executed by the users.
614.IP \(bu \nn
615Have
616.I A
617set up
618.I B
619to contain copies of
620.B ci
621and
--- 106 unchanged lines hidden (view full) ---
728The
729.B \s-1RCSINIT\s0
730options are prepended to the argument lists of most \*r commands.
731Useful
732.B \s-1RCSINIT\s0
733options include
734.BR \-q ,
735.BR \-V ,
736and
737.BR \-x .
738.TP
739.B \s-1TMPDIR\s0
740Name of the temporary directory.
741If not set, the environment variables
742.B \s-1TMP\s0
743and
744.B \s-1TEMP\s0
745are inspected instead and the first value found is taken;
--- 4 unchanged lines hidden (view full) ---
750For each revision,
751.B ci
752prints the \*r file, the working file, and the number
753of both the deposited and the preceding revision.
754The exit status is zero if and only if all operations were successful.
755.SH IDENTIFICATION
756Author: Walter F. Tichy.
757.br
758Revision Number: \*(Rv; Release Date: \*(Dt.
759.br
760Copyright \(co 1982, 1988, 1989 by Walter F. Tichy.
761.br
762Copyright \(co 1990, 1991 by Paul Eggert.
763.SH "SEE ALSO"
764co(1), ident(1), make(1), rcs(1), rcsclean(1), rcsdiff(1),
765rcsintro(1), rcsmerge(1), rlog(1), rcsfile(5)
766.br
767Walter F. Tichy,
768\*r\*-A System for Version Control,
769.I "Software\*-Practice & Experience"
770.BR 15 ,
7717 (July 1985), 637-654.
772.br