ci.1 revision 9
1.de Id 2.ds Rv \\$3 3.ds Dt \\$4 4.. 5.Id $Id: ci.1,v 5.9 1991/10/07 17:32:46 eggert Exp $ 6.ds r \&\s-1RCS\s0 7.if n .ds - \%-- 8.if t .ds - \(em 9.TH CI 1 \*(Dt GNU 10.SH NAME 11ci \- check in RCS revisions 12.SH SYNOPSIS 13.B ci 14.RI [ options ] " file " .\|.\|. 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)). 44A lock held by someone else may be broken with the 45.B rcs 46command. 47.PP 48Unless the 49.B \-f 50option is given, 51.B ci 52checks whether the revision to be deposited differs from the preceding one. 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 , 108.BR \-I , 109.BR \-k , 110.BR \-l , 111.BR \-M , 112.BR \-q , 113.BR \-r , 114or 115.BR \-u . 116.I rev 117may be symbolic, numeric, or mixed. 118If 119.I rev 120is 121.BR $ , 122.B ci 123determines the revision number from keyword values in the working file. 124.PP 125If 126.I rev 127is a revision number, it must be higher than the latest 128one on the branch to which 129.I rev 130belongs, or must start a new branch. 131.PP 132If 133.I rev 134is a branch rather than a revision number, 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 175.BR \-r [\f2rev\fP] 176checks in a revision, releases the corresponding lock, and 177removes the working file. This is the default. 178.RS 179.PP 180The 181.B \-r 182option has an unusual meaning in 183.BR ci . 184In other \*r commands, 185.B \-r 186merely specifies a revision number, 187but in 188.B ci 189it also releases a lock and removes the working file. 190See 191.B \-u 192for a tricky example. 193.RE 194.TP 195.BR \-l [\f2rev\fP] 196works like 197.BR \-r , 198except it performs an additional 199.B "co\ \-l" 200for the 201deposited revision. Thus, the deposited revision is immediately 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 , 216.BR \-r , 217and 218.B \-u 219options are mutually exclusive and silently override each other. 220For example, 221.B "ci\ \-u\ \-r" 222is equivalent to 223.B "ci\ \-r" 224because 225.B \-r 226overrides 227.BR \-u . 228.RE 229.TP 230.BR \-f [\f2rev\fP] 231forces a deposit; the new revision is deposited even it is not different 232from the preceding one. 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. 247The extracted keyword values and the default log message may be overridden 248with the options 249.BR \-d , 250.BR \-m , 251.BR \-s , 252.BR \-w , 253and any option that carries a revision number. 254.TP 255.BR \-q [\f2rev\fP] 256quiet mode; diagnostic output is not printed. 257A revision that is not different from the preceding one is not deposited, 258unless 259.B \-f 260is given. 261.TP 262.BR \-I [\f2rev\fP] 263interactive mode; 264the user is prompted and questioned 265even if the standard input is not a terminal. 266.TP 267.BR \-d "[\f2date\fP]" 268uses 269.I date 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. 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 329may not begin with 330.BR \- . 331.TP 332.BI \-t\- string 333Write descriptive text from the 334.I string 335into the \*r file, deleting the existing text. 336.RS 337.PP 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 359.BI \-w "login" 360uses 361.I login 362for the author field of the deposited revision. 363Useful for lying about the author, and for 364.B \-k 365if no author is available. 366.TP 367.BI \-V n 368Emulate \*r version 369.IR n . 370See 371.BR co (1) 372for details. 373.TP 374.BI \-x "suffixes" 375specifies the suffixes for \*r files. 376A nonempty suffix matches any pathname ending in the suffix. 377An empty suffix matches any pathname of the form 378.BI RCS/ file 379or 380.IB path /RCS/ file. 381The 382.B \-x 383option can specify a list of suffixes 384separated by 385.BR / . 386For example, 387.B \-x,v/ 388specifies two suffixes: 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/ 401for hosts like Unix that permit commas in file names, 402and is empty (i.e. just the empty suffix) for other hosts. 403.SH "FILE NAMING" 404Pairs of \*r files and working files may be specified in three ways 405(see also the 406example section). 407.PP 4081) Both the \*r file and the working file are given. The \*r pathname is of 409the form 410.IB path1 / workfileX 411and the working pathname is of the form 412.IB path2 / workfile 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 / 426must be 427.B RCS/ 428or must end in 429.BR /RCS/ . 430.PP 4312) Only the \*r file is given. Then the working file is created in the current 432directory and its name is derived from the name of the \*r file 433by removing 434.IB path1 / 435and the suffix 436.IR X . 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 519Several temporary files may be created in the directory containing 520the working file, and also in the temporary directory (see 521.B \s-1TMPDIR\s0 522under 523.BR \s-1ENVIRONMENT\s0 ). 524A semaphore file or files are created in the directory containing the \*r file. 525With a nonempty suffix, the semaphore names begin with 526the first character of the suffix; therefore, do not specify an suffix 527whose first character could be that of a working filename. 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. 579.nr n \w'\(bu '+1n-1/1n 580.IP \(bu \nn 581Check that the host supports \*r setuid use. 582Consult a trustworthy expert if there are any doubts. 583It is best if the 584.B seteuid() 585system call works as described in Posix 1003.1a Draft 5, 586because \*r can switch back and forth easily 587between real and effective users, even if the real user is 588.BR root . 589If not, the second best is if the 590.B setuid() 591system call supports saved setuid 592(the {\s-1_POSIX_SAVED_IDS\s0} behavior of Posix 1003.1-1990); 593this fails only if the real user is 594.BR root . 595If \*r detects any failure in setuid, it quits immediately. 596.IP \(bu \nn 597Choose a user 598.I A 599to serve as \*r administrator for the set of users. 600Only 601.I A 602will be able to invoke the 603.B rcs 604command on the users' \*r files. 605.I A 606should not be 607.B root 608or any other user with special powers. 609Mutually suspicious sets of users should use different administrators. 610.IP \(bu \nn 611Choose a path name 612.I B 613that will be a directory of files to be executed by the users. 614.IP \(bu \nn 615Have 616.I A 617set up 618.I B 619to contain copies of 620.B ci 621and 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 , 736and 737.BR \-x . 738.TP 739.B \s-1TMPDIR\s0 740Name of the temporary directory. 741If not set, the environment variables 742.B \s-1TMP\s0 743and 744.B \s-1TEMP\s0 745are inspected instead and the first value found is taken; 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 758Revision Number: \*(Rv; Release Date: \*(Dt. 759.br 760Copyright \(co 1982, 1988, 1989 by Walter F. Tichy. 761.br 762Copyright \(co 1990, 1991 by Paul Eggert. 763.SH "SEE ALSO" 764co(1), ident(1), make(1), rcs(1), rcsclean(1), rcsdiff(1), 765rcsintro(1), rcsmerge(1), rlog(1), rcsfile(5) 766.br 767Walter F. Tichy, 768\*r\*-A System for Version Control, 769.I "Software\*-Practice & Experience" 770.BR 15 , 7717 (July 1985), 637-654. 772.br 773