ci.1 revision 50472
1.de Id 2.ds Rv \\$3 3.ds Dt \\$4 4.. 5.Id $FreeBSD: head/gnu/usr.bin/rcs/ci/ci.1 50472 1999-08-27 23:37:10Z peter $ 6.ds i \&\s-1ISO\s0 7.ds r \&\s-1RCS\s0 8.ds u \&\s-1UTC\s0 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)). 46A lock held by someone else can be broken with the 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 , 111.BR \-I , 112.BR \-j , 113.BR \-k , 114.BR \-l , 115.BR \-M , 116.BR \-q , 117.BR \-r , 118or 119.BR \-u . 120.I rev 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. 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 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 196.BI \-r rev 197Check in revision 198.IR rev . 199.TP 200.BR \-r 201The bare 202.B \-r 203option (without any revision) has an unusual meaning in 204.BR ci . 205With other \*r commands, a bare 206.B \-r 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 216.B \-u 217options established by shell aliases or scripts. 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 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" 249because bare 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. 272The extracted keyword values and the default log message can be overridden 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 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. 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 374cannot begin with 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 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 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 461.BI RCS/ path 462or 463.IB path1 /RCS/ path2. 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/ 484for hosts like Unix that permit commas in filenames, 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. 525.SH "FILE NAMING" 526Pairs of \*r files and working files can be specified in three ways 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 / 548must start with 549.B RCS/ 550or must contain 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 641Temporary files are created in the directory containing 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. 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 705Check that the host supports \*r setuid use. 706Consult a trustworthy expert if there are any doubts. 707It is best if the 708.B seteuid 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 714.B setuid 715system call supports saved setuid 716(the {\s-1_POSIX_SAVED_IDS\s0} behavior of Posix 1003.1-1990); 717this fails only if the real or effective user is 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 726can invoke the 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 735Choose a pathname 736.I B 737to be a directory of files to be executed by the users. 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 , 861and 862.BR \-z . 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 883Manual Page Revision: \*(Rv; Release Date: \*(Dt. 884.br 885Copyright \(co 1982, 1988, 1989 Walter F. Tichy. 886.br 887Copyright \(co 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert. 888.SH "SEE ALSO" 889co(1), 890ident(1), make(1), rcs(1), rcsclean(1), rcsdiff(1), 891rcsintro(1), rcsmerge(1), rlog(1), setuid(2), rcsfile(5) 892.br 893Walter F. Tichy, 894\*r\*-A System for Version Control, 895.I "Software\*-Practice & Experience" 896.BR 15 , 8977 (July 1985), 637-654. 898.br 899