1.de Id 2.ds Rv \\$3 3.ds Dt \\$4 4.. |
5.Id $Id: ci.1,v 5.17 1995/06/16 06:19:24 eggert Exp $ 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 " .\|.\|. --- 21 unchanged lines hidden (view full) --- 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. --- 47 unchanged lines hidden (view full) --- 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, --- 32 unchanged lines hidden (view full) --- 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 --- 6 unchanged lines hidden (view full) --- 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. --- 6 unchanged lines hidden (view full) --- 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 --- 21 unchanged lines hidden (view full) --- 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 --- 14 unchanged lines hidden (view full) --- 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 --- 13 unchanged lines hidden (view full) --- 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: --- 4 unchanged lines hidden (view full) --- 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 --- 5 unchanged lines hidden (view full) --- 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 . --- 74 unchanged lines hidden (view full) --- 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. --- 43 unchanged lines hidden (view full) --- 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 --- 106 unchanged lines hidden (view full) --- 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; --- 4 unchanged lines hidden (view full) --- 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), 890emacs(1), 891ident(1), make(1), rcs(1), rcsclean(1), rcsdiff(1), 892rcsintro(1), rcsmerge(1), rlog(1), setuid(2), rcsfile(5) |
893.br 894Walter F. Tichy, 895\*r\*-A System for Version Control, 896.I "Software\*-Practice & Experience" 897.BR 15 , 8987 (July 1985), 637-654. 899.br |