1.de Id 2.ds Rv \\$3 3.ds Dt \\$4 4..
| 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 $
| 5.Id $Id: ci.1,v 5.17 1995/06/16 06:19:24 eggert Exp $ 6.ds i \&\s-1ISO\s0
|
6.ds r \&\s-1RCS\s0
| 7.ds r \&\s-1RCS\s0
|
| 8.ds u \&\s-1UTC\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)).
| 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)).
|
44A lock held by someone else may be broken with the
| 46A lock held by someone else can 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 ,
| 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 ,
|
108.BR \-I ,
| 111.BR \-I ,
|
| 112.BR \-j ,
|
109.BR \-k , 110.BR \-l , 111.BR \-M , 112.BR \-q , 113.BR \-r , 114or 115.BR \-u . 116.I rev
| 113.BR \-k , 114.BR \-l , 115.BR \-M , 116.BR \-q , 117.BR \-r , 118or 119.BR \-u . 120.I rev
|
117may be symbolic, numeric, or mixed.
| 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.
|
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
| 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
|
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
| 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
|
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
| 196.BI \-r rev 197Check in revision 198.IR rev . 199.TP 200.BR \-r 201The bare
|
181.B \-r
| 202.B \-r
|
182option has an unusual meaning in
| 203option (without any revision) has an unusual meaning in
|
183.BR ci .
| 204.BR ci .
|
184In other \*r commands,
| 205With other \*r commands, a bare
|
185.B \-r
| 206.B \-r
|
186merely specifies a revision number, 187but in 188.B ci 189it also releases a lock and removes the working file. 190See
| 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
|
191.B \-u
| 216.B \-u
|
192for a tricky example. 193.RE
| 217options established by shell aliases or scripts.
|
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 ,
| 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
|
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"
| 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"
|
224because
| 249because bare
|
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.
| 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.
|
247The extracted keyword values and the default log message may be overridden
| 272The extracted keyword values and the default log message can 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
| 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
|
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.
| 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.
|
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
| 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
|
329may not begin with
| 374cannot 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
| 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
|
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
| 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
|
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
| 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
|
378.BI RCS/ file
| 461.BI RCS/ path
|
379or
| 462or
|
380.IB path /RCS/ file.
| 463.IB path1 /RCS/ path2.
|
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/
| 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/
|
401for hosts like Unix that permit commas in file names,
| 484for hosts like Unix that permit commas in filenames,
|
402and is empty (i.e. just the empty suffix) for other hosts.
| 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.
|
403.SH "FILE NAMING"
| 525.SH "FILE NAMING"
|
404Pairs of \*r files and working files may be specified in three ways
| 526Pairs of \*r files and working files can 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 /
| 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 /
|
426must be
| 548must start with
|
427.B RCS/
| 549.B RCS/
|
428or must end in
| 550or must contain
|
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
| 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
|
519Several temporary files may be created in the directory containing
| 641Temporary files are 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.
| 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.
|
579.nr n \w'\(bu '+1n-1/1n 580.IP \(bu \nn
| 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
|
581Check that the host supports \*r setuid use. 582Consult a trustworthy expert if there are any doubts. 583It is best if the
| 705Check that the host supports \*r setuid use. 706Consult a trustworthy expert if there are any doubts. 707It is best if the
|
584.B seteuid()
| 708.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
| 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
|
590.B setuid()
| 714.B setuid
|
591system call supports saved setuid 592(the {\s-1_POSIX_SAVED_IDS\s0} behavior of Posix 1003.1-1990);
| 715system call supports saved setuid 716(the {\s-1_POSIX_SAVED_IDS\s0} behavior of Posix 1003.1-1990);
|
593this fails only if the real user is
| 717this fails only if the real or effective 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
| 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
|
602will be able to invoke the
| 726can 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
| 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
|
611Choose a path name
| 735Choose a pathname
|
612.I B
| 736.I B
|
613that will be a directory of files to be executed by the users.
| 737to 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 ,
| 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 ,
|
736and
| 861and
|
737.BR \-x .
| 862.BR \-z .
|
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
| 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
|
758Revision Number: \*(Rv; Release Date: \*(Dt.
| 883Manual Page Revision: \*(Rv; Release Date: \*(Dt.
|
759.br
| 884.br
|
760Copyright \(co 1982, 1988, 1989 by Walter F. Tichy.
| 885Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
|
761.br
| 886.br
|
762Copyright \(co 1990, 1991 by Paul Eggert.
| 887Copyright \(co 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert.
|
763.SH "SEE ALSO"
| 888.SH "SEE ALSO"
|
764co(1), ident(1), make(1), rcs(1), rcsclean(1), rcsdiff(1), 765rcsintro(1), rcsmerge(1), rlog(1), rcsfile(5)
| 889co(1), 890emacs(1), 891ident(1), make(1), rcs(1), rcsclean(1), rcsdiff(1), 892rcsintro(1), rcsmerge(1), rlog(1), setuid(2), 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
| 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
|