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