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