1CI(1)                       General Commands Manual                      CI(1)
2
3
4

NAME

6       ci - check in RCS revisions
7

SYNOPSIS

9       ci [options] file ...
10

DESCRIPTION

12       ci stores new revisions into RCS files.  Each file name matching an RCS
13       suffix is taken to be an RCS file.  All others are assumed to be  work‐
14       ing  files  containing new revisions.  ci deposits the contents of each
15       working file into the corresponding RCS file.  If only a  working  file
16       is  given, ci tries to find the corresponding RCS file in an RCS subdi‐
17       rectory and then in the working file's directory.   For  more  details,
18       see FILE NAMING below.
19
20       For  ci  to work, the caller's login must be on the access list, except
21       if the access list is empty or the caller is the superuser or the owner
22       of  the  file.  To append a new revision to an existing branch, the tip
23       revision on that branch must be locked by the caller.  Otherwise,  only
24       a  new branch can be created.  This restriction is not enforced for the
25       owner of the file if non-strict locking is used (see rcs(1)).   A  lock
26       held by someone else can be broken with the rcs command.
27
28       Unless the -f option is given, ci checks whether the revision to be de‐
29       posited differs from the preceding one.  If not, instead of creating  a
30       new  revision  ci reverts to the preceding one.  To revert, ordinary ci
31       removes the working file and any lock; ci -l keeps  and  ci -u  removes
32       any  lock,  and  then  they both generate a new working file much as if
33       co -l or co -u had been applied to the preceding  revision.   When  re‐
34       verting, any -n and -s options apply to the preceding revision.
35
36       For  each  revision  deposited,  ci prompts for a log message.  The log
37       message should summarize the change and must be terminated  by  end-of-
38       file or by a line containing . by itself.  If several files are checked
39       in ci asks whether to reuse the previous log message.  If the  standard
40       input is not a terminal, ci suppresses the prompt and uses the same log
41       message for all files.  See also -m.
42
43       If the RCS file does not exist, ci creates it and deposits the contents
44       of the working file as the initial revision (default number: 1.1).  The
45       access list is initialized to empty.  Instead of the  log  message,  ci
46       requests descriptive text (see -t below).
47
48       The number rev of the deposited revision can be given by any of the op‐
49       tions -f, -i, -I, -j, -k, -l, -M, -q, -r, or -u.  rev can be  symbolic,
50       numeric,  or mixed.  Symbolic names in rev must already be defined; see
51       the -n and -N options for assigning names during checkin.  If rev is $,
52       ci  determines  the  revision number from keyword values in the working
53       file.
54
55       If rev begins with a period, then  the  default  branch  (normally  the
56       trunk) is prepended to it.  If rev is a branch number followed by a pe‐
57       riod, then the latest revision on that branch is used.
58
59       If rev is a revision number, it must be higher than the latest  one  on
60       the branch to which rev belongs, or must start a new branch.
61
62       If  rev  is a branch rather than a revision number, the new revision is
63       appended to that branch.  The level number is obtained by  incrementing
64       the  tip revision number of that branch.  If rev indicates a non-exist‐
65       ing branch, that branch is created with the initial  revision  numbered
66       rev.1.
67
68       If  rev is omitted, ci tries to derive the new revision number from the
69       caller's last lock.  If the caller has locked the  tip  revision  of  a
70       branch,  the new revision is appended to that branch.  The new revision
71       number is obtained by incrementing the tip  revision  number.   If  the
72       caller locked a non-tip revision, a new branch is started at that revi‐
73       sion by incrementing the highest branch number at that  revision.   The
74       default initial branch and level numbers are 1.
75
76       If  rev  is  omitted  and the caller has no lock, but owns the file and
77       locking is not set to strict, then the revision is appended to the  de‐
78       fault branch (normally the trunk; see the -b option of rcs(1)).
79
80       Exception:  On the trunk, revisions can be appended to the end, but not
81       inserted.
82

OPTIONS

84       -rrev  Check in revision rev.
85
86       -r     The bare -r option (without any revision) has an unusual meaning
87              in  ci.  With other RCS commands, a bare -r option specifies the
88              most recent revision on the default branch, but with ci, a  bare
89              -r option reestablishes the default behavior of releasing a lock
90              and removing the working file, and is used to override  any  de‐
91              fault -l or -u options established by shell aliases or scripts.
92
93       -l[rev]
94              works  like  -r,  except it performs an additional co -l for the
95              deposited revision.  Thus, the deposited revision is immediately
96              checked out again and locked.  This is useful for saving a revi‐
97              sion although  one  wants  to  continue  editing  it  after  the
98              checkin.
99
100       -u[rev]
101              works like -l, except that the deposited revision is not locked.
102              This lets one read the working file immediately after checkin.
103
104              The -l, bare -r, and  -u  options  are  mutually  exclusive  and
105              silently  override each other.  For example, ci -u -r is equiva‐
106              lent to ci -r because bare -r overrides -u.
107
108       -f[rev]
109              forces a deposit; the new revision is deposited even it  is  not
110              different from the preceding one.
111
112       -k[rev]
113              searches  the  working  file for keyword values to determine its
114              revision number, creation date, state, and author  (see  co(1)),
115              and  assigns these values to the deposited revision, rather than
116              computing them locally.  It also generates a default login  mes‐
117              sage noting the login of the caller and the actual checkin date.
118              This option is useful for  software  distribution.   A  revision
119              that  is  sent to several sites should be checked in with the -k
120              option at these sites to preserve the original number, date, au‐
121              thor,  and  state.  The extracted keyword values and the default
122              log message can be overridden with the options -d, -m,  -s,  -w,
123              and any option that carries a revision number.
124
125       -q[rev]
126              quiet  mode;  diagnostic output is not printed.  A revision that
127              is not different from the preceding one is not deposited, unless
128              -f is given.
129
130       -i[rev]
131              initial checkin; report an error if the RCS file already exists.
132              This avoids race conditions in certain applications.
133
134       -j[rev]
135              just checkin and do not initialize; report an error if  the  RCS
136              file does not already exist.
137
138       -I[rev]
139              interactive  mode;  the  user is prompted and questioned even if
140              the standard input is not a terminal.
141
142       -d[date]
143              uses date for the checkin date and time.  The date is  specified
144              in  free format as explained in co(1).  This is useful for lying
145              about the checkin date, and for -k if no date is available.   If
146              date  is  empty, the working file's time of last modification is
147              used.
148
149       -M[rev]
150              Set the modification time on any new working file to be the date
151              of  the retrieved revision.  For example, ci -d -M -u f does not
152              alter f's modification time, even if f's contents change due  to
153              keyword substitution.  Use this option with care; it can confuse
154              make(1).
155
156       -m[msg]
157              uses the string msg as the log message for all revisions checked
158              in.   If  msg  is omitted, it defaults to "*** empty log message
159              ***".  By convention, log messages that start with  #  are  com‐
160              ments  and  are ignored by programs like GNU Emacs's vc package.
161              Also, log messages that  start  with  {clumpname}  (followed  by
162              white  space) are meant to be clumped together if possible, even
163              if they are associated with different files; the {clumpname} la‐
164              bel  is used only for clumping, and is not considered to be part
165              of the log message itself.
166
167       -nname assigns the symbolic name name to the number of  the  checked-in
168              revision.   ci  prints  an  error message if name is already as‐
169              signed to another number.
170
171       -Nname same as -n, except that it overrides a  previous  assignment  of
172              name.
173
174       -sstate
175              sets  the  state  of  the  checked-in revision to the identifier
176              state.  The default state is Exp.
177
178       -tfile writes descriptive text from the contents of the named file into
179              the RCS file, deleting the existing text.  The file cannot begin
180              with -.
181
182       -t-string
183              Write descriptive text from the string into the RCS file, delet‐
184              ing the existing text.
185
186              The -t option, in both its forms, has effect only during an ini‐
187              tial checkin; it is silently ignored otherwise.
188
189              During the initial checkin, if -t is not given, ci  obtains  the
190              text from standard input, terminated by end-of-file or by a line
191              containing . by itself.  The user is prompted for  the  text  if
192              interaction is possible; see -I.
193
194              For backward compatibility with older versions of RCS, a bare -t
195              option is ignored.
196
197       -T     Set the RCS file's modification time to the new revision's  time
198              if  the  former precedes the latter and there is a new revision;
199              preserve the RCS file's modification  time  otherwise.   If  you
200              have  locked a revision, ci usually updates the RCS file's modi‐
201              fication time to the current time, because the lock is stored in
202              the  RCS  file  and  removing the lock requires changing the RCS
203              file.  This can create an RCS file newer than the  working  file
204              in  one of two ways: first, ci -M can create a working file with
205              a date before the current time; second, when  reverting  to  the
206              previous revision the RCS file can change while the working file
207              remains unchanged.  These two cases can cause excessive recompi‐
208              lation caused by a make(1) dependency of the working file on the
209              RCS file.  The -T option inhibits this  recompilation  by  lying
210              about  the  RCS  file's date.  Use this option with care; it can
211              suppress recompilation even when a checkin of one  working  file
212              should  affect another working file associated with the same RCS
213              file.  For example, suppose the RCS file's time  is  01:00,  the
214              (changed)  working  file's time is 02:00, some other copy of the
215              working file has a time of 03:00, and the current time is 04:00.
216              Then  ci -d -T  sets the RCS file's time to 02:00 instead of the
217              usual 04:00; this causes make(1) to think (incorrectly) that the
218              other copy is newer than the RCS file.
219
220       -wlogin
221              uses login for the author field of the deposited revision.  Use‐
222              ful for lying about the author, and  for  -k  if  no  author  is
223              available.
224
225       -V     Print RCS's version number.
226
227       -Vn    Emulate RCS version n.  See co(1) for details.
228
229       -xsuffixes
230              specifies the suffixes for RCS files.  A nonempty suffix matches
231              any file name ending in the suffix.  An empty suffix matches any
232              file  name  of the form RCS/frag or frag1/RCS/frag2.  The -x op‐
233              tion can specify a list of suffixes separated by /.   For  exam‐
234              ple,  -x,v/ specifies two suffixes: ,v and the empty suffix.  If
235              two or more suffixes are specified, they are tried in order when
236              looking  for  an  RCS file; the first one that works is used for
237              that file.  If no RCS file is found but an RCS file can be  cre‐
238              ated,  the  suffixes are tried in order to determine the new RCS
239              file's name.  The default for  suffixes  is  installation-depen‐
240              dent;  normally it is ,v/ for hosts like Unix that permit commas
241              in file names, and is empty (i.e. just  the  empty  suffix)  for
242              other hosts.
243
244       -zzone specifies  the  date  output format in keyword substitution, and
245              specifies the default time zone for date in the  -ddate  option.
246              The  zone  should be empty, a numeric UTC offset, or the special
247              string LT for local time.  The default is an empty  zone,  which
248              uses the traditional RCS format of UTC without any time zone in‐
249              dication and with slashes separating the parts of the date; oth‐
250              erwise, times are output in ISO 8601 format with time zone indi‐
251              cation.  For example, if local time is January 11, 1990, 8pm Pa‐
252              cific  Standard  Time, eight hours west of UTC, then the time is
253              output as follows:
254
255                     option    time output
256                     -z        1990/01/12 04:00:00        (default)
257                     -zLT      1990-01-11 20:00:00-08
258                     -z+05:30  1990-01-12 09:30:00+05:30
259
260              The -z option does not affect dates stored in RCS  files,  which
261              are always UTC.
262

FILE NAMING

264       Pairs  of  RCS  files  and working files can be specified in three ways
265       (see also the example section).
266
267       1) Both the RCS file and the working file are given.  The RCS file name
268       is of the form frag1/workfileX and the working file name is of the form
269       frag2/workfile where frag1/  and  frag2/  are  (possibly  different  or
270       empty) file names, workfile is a file name, and X is an RCS suffix.  If
271       X is empty, frag1/ must start with RCS/ or must contain /RCS/.
272
273       2) Only the RCS file is given.  Then the working file is created in the
274       current directory and its name is derived from the RCS file name by re‐
275       moving frag1/ and the suffix X.
276
277       3) Only the working file is given.  Then ci considers each RCS suffix X
278       in turn, looking for an RCS file of the form frag2/RCS/workfileX or (if
279       the former is not found and X is nonempty) frag2/workfileX.
280
281       If the RCS file is specified without a file name in 1) and 2), ci looks
282       for  the  RCS file first in the directory ./RCS and then in the current
283       directory.
284
285       ci reports an error if an attempt to open an RCS file fails for an  un‐
286       usual reason, even if the RCS file's name is just one of several possi‐
287       bilities.  For example, to suppress use of RCS commands in a  directory
288       d, create a regular file named d/RCS so that casual attempts to use RCS
289       commands in d fail because d/RCS is not a directory.
290

EXAMPLES

292       Suppose ,v is an RCS suffix and the current directory contains a subdi‐
293       rectory  RCS  with an RCS file io.c,v.  Then each of the following com‐
294       mands check in a copy of io.c into RCS/io.c,v as the  latest  revision,
295       removing io.c.
296
297              ci  io.c;    ci  RCS/io.c,v;   ci  io.c,v;
298              ci  io.c  RCS/io.c,v;    ci  io.c  io.c,v;
299              ci  RCS/io.c,v  io.c;    ci  io.c,v  io.c;
300
301       Suppose  instead that the empty suffix is an RCS suffix and the current
302       directory contains a subdirectory RCS with an RCS file io.c.  The  each
303       of the following commands checks in a new revision.
304
305              ci  io.c;    ci  RCS/io.c;
306              ci  io.c  RCS/io.c;
307              ci  RCS/io.c  io.c;
308

FILE MODES

310       An  RCS  file  created  by ci inherits the read and execute permissions
311       from the working file.  If the RCS file exists  already,  ci  preserves
312       its  read  and execute permissions.  ci always turns off all write per‐
313       missions of RCS files.
314

FILES

316       Temporary files are created in the  directory  containing  the  working
317       file,  and  also  in the temporary directory (see TMPDIR under ENVIRON‐
318       MENT).  A semaphore file or files are created in the directory contain‐
319       ing  the  RCS  file.  With a nonempty suffix, the semaphore names begin
320       with the first character of the suffix; therefore, do  not  specify  an
321       suffix  whose  first  character  could  be that of a working file name.
322       With an empty suffix, the semaphore names end with _  so  working  file
323       names should not end in _.
324
325       ci never changes an RCS file or working file.  Normally, ci unlinks the
326       file and creates a new one; but instead of breaking a chain of  one  or
327       more symbolic links to an RCS file, it unlinks the destination file in‐
328       stead.  Therefore, ci breaks any hard or symbolic links to any  working
329       file  it changes; and hard links to RCS files are ineffective, but sym‐
330       bolic links to RCS files are preserved.
331
332       The effective user must be able to search and write the directory  con‐
333       taining the RCS file.  Normally, the real user must be able to read the
334       RCS and working files and to search and write the directory  containing
335       the  working  file;  however, some older hosts cannot easily switch be‐
336       tween real and effective users, so on these hosts the effective user is
337       used for all accesses.  The effective user is the same as the real user
338       unless your copies of ci and co have setuid privileges.   As  described
339       in  the  next section, these privileges yield extra security if the ef‐
340       fective user owns all RCS files and directories, and if only the effec‐
341       tive user can write RCS directories.
342
343       Users can control access to RCS files by setting the permissions of the
344       directory containing the files; only users with write access to the di‐
345       rectory  can use RCS commands to change its RCS files.  For example, in
346       hosts that allow a user to belong to several groups,  one  can  make  a
347       group's  RCS  directories  writable  to that group only.  This approach
348       suffices for informal projects, but it means that any group member  can
349       arbitrarily  change the group's RCS files, and can even remove them en‐
350       tirely.  Hence more formal projects sometimes  distinguish  between  an
351       RCS  administrator,  who  can  change  the RCS files at will, and other
352       project members, who can check in new revisions  but  cannot  otherwise
353       change the RCS files.
354

SETUID USE

356       To prevent anybody but their RCS administrator from deleting revisions,
357       a set of users can employ setuid privileges as follows.
358
359       • Check that the host supports RCS setuid use.  Consult  a  trustworthy
360         expert  if  there  are  any doubts.  It is best if the seteuid system
361         call works as described in Posix 1003.1a Draft  5,  because  RCS  can
362         switch  back  and forth easily between real and effective users, even
363         if the real user is root.  If not, the second best is if  the  setuid
364         system call supports saved setuid (the {_POSIX_SAVED_IDS} behavior of
365         Posix 1003.1-1990); this fails only if the real or effective user  is
366         root.  If RCS detects any failure in setuid, it quits immediately.
367
368       • Choose  a  user A to serve as RCS administrator for the set of users.
369         Only A can invoke the rcs command on the users' RCS files.  A  should
370         not  be  root or any other user with special powers.  Mutually suspi‐
371         cious sets of users should use different administrators.
372
373       • Choose a file name B to be a directory of files to be executed by the
374         users.
375
376       • Have  A  set up B to contain copies of ci and co that are setuid to A
377         by copying the commands from their standard installation directory  D
378         as follows:
379
380              mkdir  B
381              cp  D/c[io]  B
382              chmod  go-w,u+s  B/c[io]
383
384       • Have each user prepend B to their command search path as follows:
385
386              PATH=B:$PATH;  export  PATH  # ordinary shell
387              set  path=(B  $path)  # C shell
388
389       • Have  A  create  each  RCS directory R with write access only to A as
390         follows:
391
392              mkdir  R
393              chmod  go-w  R
394
395       • If you want to let only certain users read the  RCS  files,  put  the
396         users into a group G, and have A further protect the RCS directory as
397         follows:
398
399              chgrp  G  R
400              chmod  g-w,o-rwx  R
401
402       • Have A copy old RCS files (if any) into R,  to  ensure  that  A  owns
403         them.
404
405       • An RCS file's access list limits who can check in and lock revisions.
406         The default access list is empty, which grants checkin access to any‐
407         one  who  can  read  the RCS file.  If you want limit checkin access,
408         have A invoke  rcs -a  on  the  file;  see  rcs(1).   In  particular,
409         rcs -e -aA limits access to just A.
410
411       • Have  A  initialize  any  new  RCS  files  with rcs -i before initial
412         checkin, adding the -a option if you want to limit checkin access.
413
414       • Give setuid privileges only to ci, co, and rcsclean; do not give them
415         to rcs or to any other command.
416
417       • Do  not  use  other setuid commands to invoke RCS commands; setuid is
418         trickier than you think!
419

ENVIRONMENT

421       RCSINIT
422              Options prepended to the argument list, separated by spaces.   A
423              backslash  escapes spaces within an option.  The RCSINIT options
424              are prepended to the argument lists of most RCS commands.   Use‐
425              ful RCSINIT options include -q, -V, -x, and -z.
426
427       RCS_MEM_LIMIT
428              Normally,  for  speed,  commands  either memory map or copy into
429              memory the RCS file if its size is less than  the  memory-limit,
430              currently  defaulting  to  ``unlimited''.   Otherwise (or if the
431              initially-tried speedy ways fail), the commands fall back to us‐
432              ing  standard  i/o routines.  You can adjust the memory limit by
433              setting RCS_MEM_LIMIT to a numeric value lim (measured in  kilo‐
434              bytes).   An empty value is silently ignored.  As a side effect,
435              specifying RCS_MEM_LIMIT inhibits fall-back to slower routines.
436
437       TMPDIR Name of the temporary directory.  If not  set,  the  environment
438              variables TMP and TEMP are inspected instead and the first value
439              found is taken; if none of them are set,  a  host-dependent  de‐
440              fault is used, typically /tmp.
441

DIAGNOSTICS

443       For  each  revision,  ci prints the RCS file, the working file, and the
444       number of both the deposited and the preceding revision.  The exit sta‐
445       tus is zero if and only if all operations were successful.
446

IDENTIFICATION

448       Author: Walter F. Tichy.
449       Manual Page Revision: 5.10.1; Release Date: 2022-11-07.
450       Copyright © 2010-2022 Thien-Thi Nguyen.
451       Copyright © 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert.
452       Copyright © 1982, 1988, 1989 Walter F. Tichy.
453

SEE ALSO

455       co(1),  emacs(1),  ident(1),  make(1), rcs(1), rcsclean(1), rcsdiff(1),
456       rcsmerge(1), rlog(1), setuid(2), rcsfile(5).
457
458       Walter F. Tichy, RCS--A System for Version Control,  Software--Practice
459       & Experience 15, 7 (July 1985), 637-654.
460
461       The  full  documentation for RCS is maintained as a Texinfo manual.  If
462       the info(1) and RCS programs are properly installed at your  site,  the
463       command
464
465              info rcs
466
467       should  give  you access to the complete manual.  Additionally, the RCS
468       homepage:
469
470              http://www.gnu.org/software/rcs/
471
472       has news and links to the latest release, development site, etc.
473
474
475
476GNU RCS 5.10.1                    2022-11-07                             CI(1)
Impressum