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

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