gnu/usr.bin/rcs/rcs/rcs.1

   1 .de Id
   2 .ds Rv \\$3
   3 .ds Dt \\$4
   4 ..
   5 .Id $FreeBSD$
   6 .ds r \&\s-1RCS\s0
   7 .if n .ds - \%--
   8 .if t .ds - \(em
   9 .if !\n(.g \{\
  10 .       if !\w|\*(lq| \{\
  11 .               ds lq ``
  12 .               if \w'\(lq' .ds lq "\(lq
  13 .       \}
  14 .       if !\w|\*(rq| \{\
  15 .               ds rq ''
  16 .               if \w'\(rq' .ds rq "\(rq
  17 .       \}
  18 .\}
  19 .TH RCS 1 \*(Dt GNU
  20 .SH NAME
  21 rcs \- change RCS file attributes
  22 .SH SYNOPSIS
  23 .B rcs
  24 .IR "options file " .\|.\|.
  25 .SH DESCRIPTION
  26 .B rcs
  27 creates new \*r files or changes attributes of existing ones.
  28 An \*r file contains multiple revisions of text,
  29 an access list, a change log,
  30 descriptive text,
  31 and some control attributes.
  32 For
  33 .B rcs
  34 to work, the caller's login name must be on the access list,
  35 except if the access list is empty, the caller is the owner of the file
  36 or the superuser, or
  37 the
  38 .B \-i
  39 option is present.
  40 .PP
  41 Pathnames matching an \*r suffix denote \*r files;
  42 all others denote working files.
  43 Names are paired as explained in
  44 .BR ci (1).
  45 Revision numbers use the syntax described in
  46 .BR ci (1).
  47 .SH OPTIONS
  48 .TP
  49 .B \-i
  50 Create and initialize a new \*r file, but do not deposit any revision.
  51 If the \*r file has no path prefix, try to place it
  52 first into the subdirectory
  53 .BR ./RCS ,
  54 and then into the current directory.
  55 If the \*r file
  56 already exists, print an error message.
  57 .TP
  58 .BI \-a "logins"
  59 Append the login names appearing in the comma-separated list
  60 .I logins
  61 to the access list of the \*r file.
  62 .TP
  63 .BI \-A "oldfile"
  64 Append the access list of
  65 .I oldfile
  66 to the access list of the \*r file.
  67 .TP
  68 .BR \-e [\f2logins\fP]
  69 Erase the login names appearing in the comma-separated list
  70 .I logins
  71 from the access list of the \*r file.
  72 If
  73 .I logins
  74 is omitted, erase the entire access list.
  75 .TP
  76 .BR \-b [\f2rev\fP]
  77 Set the default branch to
  78 .IR rev .
  79 If
  80 .I rev
  81 is omitted, the default
  82 branch is reset to the (dynamically) highest branch on the trunk.
  83 .TP
  84 .BI \-c string
  85 Set the comment leader to
  86 .IR string .
  87 An initial
  88 .BR ci ,
  89 or an
  90 .B "rcs\ \-i"
  91 without
  92 .BR \-c ,
  93 guesses the comment leader from the suffix of the working filename.
  94 .RS
  95 .PP
  96 This option is obsolescent, since \*r normally uses the preceding
  97 .B $\&Log$
  98 line's prefix when inserting log lines during checkout (see
  99 .BR co (1)).
 100 However, older versions of \*r use the comment leader instead of the
 101 .B $\&Log$
 102 line's prefix, so
 103 if you plan to access a file with both old and new versions of \*r,
 104 make sure its comment leader matches its
 105 .B $\&Log$
 106 line prefix.
 107 .RE
 108 .TP
 109 .BI \-k subst
 110 Set the default keyword substitution to
 111 .IR subst .
 112 The effect of keyword substitution is described in
 113 .BR co (1).
 114 Giving an explicit
 115 .B \-k
 116 option to
 117 .BR co ,
 118 .BR rcsdiff ,
 119 and
 120 .B rcsmerge
 121 overrides this default.
 122 Beware
 123 .BR "rcs\ \-kv",
 124 because
 125 .B \-kv
 126 is incompatible with
 127 .BR "co\ \-l".
 128 Use
 129 .B "rcs\ \-kkv"
 130 to restore the normal default keyword substitution.
 131 .TP
 132 .BR \-l [\f2rev\fP]
 133 Lock the revision with number
 134 .IR rev .
 135 If a branch is given, lock the latest revision on that branch.
 136 If
 137 .I rev
 138 is omitted, lock the latest revision on the default branch.
 139 Locking prevents overlapping changes.
 140 If someone else already holds the lock, the lock is broken as with
 141 .B "rcs\ \-u"
 142 (see below).
 143 .TP
 144 .BR \-u [\f2rev\fP]
 145 Unlock the revision with number
 146 .IR rev .
 147 If a branch is given, unlock the latest revision on that branch.
 148 If
 149 .I rev
 150 is omitted, remove the latest lock held by the caller.
 151 Normally, only the locker of a revision can unlock it.
 152 Somebody else unlocking a revision breaks the lock.
 153 This causes a mail message to be sent to the original locker.
 154 The message contains a commentary solicited from the breaker.
 155 The commentary is terminated by end-of-file or by a line containing
 156 .BR \&. "\ by"
 157 itself.
 158 .TP
 159 .B \-L
 160 Set locking to
 161 .IR strict .
 162 Strict locking means that the owner
 163 of an \*r file is not exempt from locking for checkin.
 164 This option should be used for files that are shared.
 165 .TP
 166 .B \-U
 167 Set locking to non-strict.  Non-strict locking means that the owner of
 168 a file need not lock a revision for checkin.
 169 This option should
 170 .I not
 171 be used for files that are shared.
 172 Whether default locking is strict is determined by your system administrator,
 173 but it is normally strict.
 174 .TP
 175 \f3\-m\fP\f2rev\fP\f3:\fP\f2msg\fP
 176 Replace revision
 177 .IR rev 's
 178 log message with
 179 .IR msg .
 180 .TP
 181 .B \-M
 182 Do not send mail when breaking somebody else's lock.
 183 This option is not meant for casual use;
 184 it is meant for programs that warn users by other means, and invoke
 185 .B "rcs\ \-u"
 186 only as a low-level lock-breaking operation.
 187 .TP
 188 \f3\-n\fP\f2name\fP[\f3:\fP[\f2rev\fP]]
 189 Associate the symbolic name
 190 .I name
 191 with the branch or
 192 revision
 193 .IR rev .
 194 Delete the symbolic name if both
 195 .B :
 196 and
 197 .I rev
 198 are omitted; otherwise, print an error message if
 199 .I name
 200 is already associated with
 201 another number.
 202 If
 203 .I rev
 204 is symbolic, it is expanded before association.
 205 A
 206 .I rev
 207 consisting of a branch number followed by a
 208 .B .\&
 209 stands for the current latest revision in the branch.
 210 A
 211 .B :
 212 with an empty
 213 .I rev
 214 stands for the current latest revision on the default branch,
 215 normally the trunk.
 216 For example,
 217 .BI "rcs\ \-n" name ":\ RCS/*"
 218 associates
 219 .I name
 220 with the current latest revision of all the named \*r files;
 221 this contrasts with
 222 .BI "rcs\ \-n" name ":$\ RCS/*"
 223 which associates
 224 .I name
 225 with the revision numbers extracted from keyword strings
 226 in the corresponding working files.
 227 .TP
 228 \f3\-N\fP\f2name\fP[\f3:\fP[\f2rev\fP]]
 229 Act like
 230 .BR \-n ,
 231 except override any previous assignment of
 232 .IR name .
 233 .TP
 234 .BI \-o range
 235 deletes (\*(lqoutdates\*(rq) the revisions given by
 236 .IR range .
 237 A range consisting of a single revision number means that revision.
 238 A range consisting of a branch number means the latest revision on that
 239 branch.
 240 A range of the form
 241 .IB rev1 : rev2
 242 means
 243 revisions
 244 .I rev1
 245 to
 246 .I rev2
 247 on the same branch,
 248 .BI : rev
 249 means from the beginning of the branch containing
 250 .I rev
 251 up to and including
 252 .IR rev ,
 253 and
 254 .IB rev :
 255 means
 256 from revision
 257 .I rev
 258 to the end of the branch containing
 259 .IR rev .
 260 None of the outdated revisions can have branches or locks.
 261 .TP
 262 .B \-q
 263 Run quietly; do not print diagnostics.
 264 .TP
 265 .B \-I
 266 Run interactively, even if the standard input is not a terminal.
 267 .TP
 268 .B \-s\f2state\fP\f1[\fP:\f2rev\fP\f1]\fP
 269 Set the state attribute of the revision
 270 .I rev
 271 to
 272 .IR state .
 273 If
 274 .I rev
 275 is a branch number, assume the latest revision on that branch.
 276 If
 277 .I rev
 278 is omitted, assume the latest revision on the default branch.
 279 Any identifier is acceptable for
 280 .IR state .
 281 A useful set of states
 282 is
 283 .B Exp
 284 (for experimental),
 285 .B Stab
 286 (for stable), and
 287 .B Rel
 288 (for
 289 released).
 290 By default,
 291 .BR ci (1)
 292 sets the state of a revision to
 293 .BR Exp .
 294 .TP
 295 .BR \-t [\f2file\fP]
 296 Write descriptive text from the contents of the named
 297 .I file
 298 into the \*r file, deleting the existing text.
 299 The
 300 .IR file
 301 pathname cannot begin with
 302 .BR \- .
 303 If
 304 .I file
 305 is omitted, obtain the text from standard input,
 306 terminated by end-of-file or by a line containing
 307 .BR \&. "\ by"
 308 itself.
 309 Prompt for the text if interaction is possible; see
 310 .BR \-I .
 311 With
 312 .BR \-i ,
 313 descriptive text is obtained
 314 even if
 315 .B \-t
 316 is not given.
 317 .TP
 318 .BI \-t\- string
 319 Write descriptive text from the
 320 .I string
 321 into the \*r file, deleting the existing text.
 322 .TP
 323 .B \-T
 324 Preserve the modification time on the \*r file
 325 unless a revision is removed.
 326 This option can suppress extensive recompilation caused by a
 327 .BR make (1)
 328 dependency of some copy of the working file on the \*r file.
 329 Use this option with care; it can suppress recompilation even when it is needed,
 330 i.e. when a change to the \*r file
 331 would mean a change to keyword strings in the working file.
 332 .TP
 333 .BI \-V
 334 Print \*r's version number.
 335 .TP
 336 .BI \-V n
 337 Emulate \*r version
 338 .IR n .
 339 See
 340 .BR co (1)
 341 for details.
 342 .TP
 343 .BI \-x "suffixes"
 344 Use
 345 .I suffixes
 346 to characterize \*r files.
 347 See
 348 .BR ci (1)
 349 for details.
 350 .TP
 351 .BI \-z zone
 352 Use
 353 .I zone
 354 as the default time zone.
 355 This option has no effect;
 356 it is present for compatibility with other \*r commands.
 357 .PP
 358 At least one explicit option must be given,
 359 to ensure compatibility with future planned extensions
 360 to the
 361 .B rcs
 362 command.
 363 .SH COMPATIBILITY
 364 The
 365 .BI \-b rev
 366 option generates an \*r file that cannot be parsed by \*r version 3 or earlier.
 367 .PP
 368 The
 369 .BI \-k subst
 370 options (except
 371 .BR \-kkv )
 372 generate an \*r file that cannot be parsed by \*r version 4 or earlier.
 373 .PP
 374 Use
 375 .BI "rcs \-V" n
 376 to make an \*r file acceptable to \*r version
 377 .I n
 378 by discarding information that would confuse version
 379 .IR n .
 380 .PP
 381 \*r version 5.5 and earlier does not support the
 382 .B \-x
 383 option, and requires a
 384 .B ,v
 385 suffix on an \*r pathname.
 386 .SH FILES
 387 .B rcs
 388 accesses files much as
 389 .BR ci (1)
 390 does,
 391 except that it uses the effective user for all accesses,
 392 it does not write the working file or its directory,
 393 and it does not even read the working file unless a revision number of
 394 .B $
 395 is specified.
 396 .SH ENVIRONMENT
 397 .TP
 398 .B \s-1RCSINIT\s0
 399 options prepended to the argument list, separated by spaces.
 400 See
 401 .BR ci (1)
 402 for details.
 403 .SH DIAGNOSTICS
 404 The \*r pathname and the revisions outdated are written to
 405 the diagnostic output.
 406 The exit status is zero if and only if all operations were successful.
 407 .SH IDENTIFICATION
 408 Author: Walter F. Tichy.
 409 .br
 410 Manual Page Revision: \*(Rv; Release Date: \*(Dt.
 411 .br
 412 Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
 413 .br
 414 Copyright \(co 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert.
 415 .SH "SEE ALSO"
 416 rcsintro(1), co(1), ci(1), ident(1), rcsclean(1), rcsdiff(1),
 417 rcsmerge(1), rlog(1), rcsfile(5)
 418 .br
 419 Walter F. Tichy,
 420 \*r\*-A System for Version Control,
 421 .I "Software\*-Practice & Experience"
 422 .BR 15 ,
 423 7 (July 1985), 637-654.
 424 .SH BUGS
 425 A catastrophe (e.g. a system crash) can cause \*r to leave behind
 426 a semaphore file that causes later invocations of \*r to claim
 427 that the \*r file is in use.
 428 To fix this, remove the semaphore file.
 429 A semaphore file's name typically begins with
 430 .B ,
 431 or ends with
 432 .BR _ .
 433 .PP
 434 The separator for revision ranges in the
 435 .B \-o
 436 option used to be
 437 .B \-
 438 instead of
 439 .BR : ,
 440 but this leads to confusion when symbolic names contain
 441 .BR \- .
 442 For backwards compatibility
 443 .B "rcs \-o"
 444 still supports the old
 445 .B \-
 446 separator, but it warns about this obsolete use.
 447 .PP
 448 Symbolic names need not refer to existing revisions or branches.
 449 For example, the
 450 .B \-o
 451 option does not remove symbolic names for the outdated revisions; you must use
 452 .B \-n
 453 to remove the names.
 454 .br