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

   1 .de Id
   2 .ds Rv \\$3
   3 .ds Dt \\$4
   4 ..
   5 .Id $FreeBSD: src/gnu/usr.bin/rcs/co/co.1,v 1.6 1999/08/27 23:36:39 peter Exp $
   6 .Id $DragonFly: src/gnu/usr.bin/rcs/co/co.1,v 1.2 2003/06/17 04:25:47 dillon Exp $
   7 .ds i \&\s-1ISO\s0
   8 .ds r \&\s-1RCS\s0
   9 .ds u \&\s-1UTC\s0
  10 .if n .ds - \%--
  11 .if t .ds - \(em
  12 .TH CO 1 \*(Dt GNU
  13 .SH NAME
  14 co \- check out RCS revisions
  15 .SH SYNOPSIS
  16 .B co
  17 .RI [ options ] " file " .\|.\|.
  18 .SH DESCRIPTION
  19 .B co
  20 retrieves a revision from each \*r file and stores it into
  21 the corresponding working file.
  22 .PP
  23 Pathnames matching an \*r suffix denote \*r files;
  24 all others denote working files.
  25 Names are paired as explained in
  26 .BR ci (1).
  27 .PP
  28 Revisions of an \*r file can be checked out locked or unlocked.  Locking a
  29 revision prevents overlapping updates.  A revision checked out for reading or
  30 processing (e.g., compiling) need not be locked.  A revision checked out
  31 for editing and later checkin must normally be locked.  Checkout with locking
  32 fails if the revision to be checked out is currently locked by another user.
  33 (A lock can be broken with
  34 .BR rcs "(1).)\ \&"
  35 Checkout with locking also requires the caller to be on the access list of
  36 the \*r file, unless he is the owner of the
  37 file or the superuser, or the access list is empty.
  38 Checkout without locking is not subject to accesslist restrictions, and is
  39 not affected by the presence of locks.
  40 .PP
  41 A revision is selected by options for revision or branch number,
  42 checkin date/time, author, or state.
  43 When the selection options
  44 are applied in combination,
  45 .B co
  46 retrieves the latest revision
  47 that satisfies all of them.
  48 If none of the selection options
  49 is specified,
  50 .B co
  51 retrieves the latest revision
  52 on the default branch (normally the trunk, see the
  53 .B \-b
  54 option of
  55 .BR rcs (1)).
  56 A revision or branch number can be attached
  57 to any of the options
  58 .BR \-f ,
  59 .BR \-I ,
  60 .BR \-l ,
  61 .BR \-M ,
  62 .BR \-p ,
  63 .BR \-q ,
  64 .BR \-r ,
  65 or
  66 .BR \-u .
  67 The options
  68 .B \-d
  69 (date),
  70 .B \-s
  71 (state), and
  72 .B \-w
  73 (author)
  74 retrieve from a single branch, the
  75 .I selected
  76 branch,
  77 which is either specified by one of
  78 .BR \-f ,
  79 \&.\|.\|.,
  80 .BR \-u ,
  81 or the default branch.
  82 .PP
  83 A
  84 .B co
  85 command applied to an \*r
  86 file with no revisions creates a zero-length working file.
  87 .B co
  88 always performs keyword substitution (see below).
  89 .SH OPTIONS
  90 .TP
  91 .BR \-r [\f2rev\fP]
  92 retrieves the latest revision whose number is less than or equal to
  93 .IR rev .
  94 If
  95 .I rev
  96 indicates a branch rather than a revision,
  97 the latest revision on that branch is retrieved.
  98 If
  99 .I rev
 100 is omitted, the latest revision on the default branch
 101 (see the
 102 .B \-b
 103 option of
 104 .BR rcs (1))
 105 is retrieved.
 106 If
 107 .I rev
 108 is
 109 .BR $ ,
 110 .B co
 111 determines the revision number from keyword values in the working file.
 112 Otherwise, a revision is composed of one or more numeric or symbolic fields
 113 separated by periods.
 114 If
 115 .I rev
 116 begins with a period,
 117 then the default branch (normally the trunk) is prepended to it.
 118 If
 119 .I rev
 120 is a branch number followed by a period,
 121 then the latest revision on that branch is used.
 122 The numeric equivalent of a symbolic field
 123 is specified with the
 124 .B \-n
 125 option of the commands
 126 .BR ci (1)
 127 and
 128 .BR rcs (1).
 129 .TP
 130 .BR \-l [\f2rev\fP]
 131 same as
 132 .BR \-r ,
 133 except that it also locks the retrieved revision for
 134 the caller.
 135 .TP
 136 .BR \-u [\f2rev\fP]
 137 same as
 138 .BR \-r ,
 139 except that it unlocks the retrieved revision if it was
 140 locked by the caller.  If
 141 .I rev
 142 is omitted,
 143 .B \-u
 144 retrieves the revision locked by the caller, if there is one; otherwise,
 145 it retrieves the latest revision on the default branch.
 146 .TP
 147 .BR \-f [\f2rev\fP]
 148 forces the overwriting of the working file;
 149 useful in connection with
 150 .BR \-q .
 151 See also
 152 .SM "FILE MODES"
 153 below.
 154 .TP
 155 .B \-kkv
 156 Generate keyword strings using the default form, e.g.\&
 157 .B "$\&Revision: \*(Rv $"
 158 for the
 159 .B Revision
 160 keyword.
 161 A locker's name is inserted in the value of the
 162 .BR Header ,
 163 .BR Id ,
 164 and
 165 .B Locker
 166 keyword strings
 167 only as a file is being locked,
 168 i.e. by
 169 .B "ci\ \-l"
 170 and
 171 .BR "co\ \-l".
 172 This is the default.
 173 .TP
 174 .B \-kkvl
 175 Like
 176 .BR \-kkv ,
 177 except that a locker's name is always inserted
 178 if the given revision is currently locked.
 179 .TP
 180 .B \-kk
 181 Generate only keyword names in keyword strings; omit their values.
 182 See
 183 .SM "KEYWORD SUBSTITUTION"
 184 below.
 185 For example, for the
 186 .B Revision
 187 keyword, generate the string
 188 .B $\&Revision$
 189 instead of
 190 .BR "$\&Revision: \*(Rv $" .
 191 This option is useful to ignore differences due to keyword substitution
 192 when comparing different revisions of a file.
 193 Log messages are inserted after
 194 .B $\&Log$
 195 keywords even if
 196 .B \-kk
 197 is specified,
 198 since this tends to be more useful when merging changes.
 199 .TP
 200 .B \-ko
 201 Generate the old keyword string,
 202 present in the working file just before it was checked in.
 203 For example, for the
 204 .B Revision
 205 keyword, generate the string
 206 .B "$\&Revision: 1.1 $"
 207 instead of
 208 .B "$\&Revision: \*(Rv $"
 209 if that is how the string appeared when the file was checked in.
 210 This can be useful for file formats
 211 that cannot tolerate any changes to substrings
 212 that happen to take the form of keyword strings.
 213 .TP
 214 .B \-kb
 215 Generate a binary image of the old keyword string.
 216 This acts like
 217 .BR \-ko ,
 218 except it performs all working file input and output in binary mode.
 219 This makes little difference on Posix and Unix hosts,
 220 but on DOS-like hosts one should use
 221 .B "rcs\ \-i\ \-kb"
 222 to initialize an \*r file intended to be used for binary files.
 223 Also, on all hosts,
 224 .BR rcsmerge (1)
 225 normally refuses to merge files when
 226 .B \-kb
 227 is in effect.
 228 .TP
 229 .B \-kv
 230 Generate only keyword values for keyword strings.
 231 For example, for the
 232 .B Revision
 233 keyword, generate the string
 234 .B \*(Rv
 235 instead of
 236 .BR "$\&Revision: \*(Rv $" .
 237 This can help generate files in programming languages where it is hard to
 238 strip keyword delimiters like
 239 .B "$\&Revision:\ $"
 240 from a string.
 241 However, further keyword substitution cannot be performed once the
 242 keyword names are removed, so this option should be used with care.
 243 Because of this danger of losing keywords,
 244 this option cannot be combined with
 245 .BR \-l ,
 246 and the owner write permission of the working file is turned off;
 247 to edit the file later, check it out again without
 248 .BR \-kv .
 249 .TP
 250 .BR \-p [\f2rev\fP]
 251 prints the retrieved revision on the standard output rather than storing it
 252 in the working file.
 253 This option is useful when
 254 .B co
 255 is part of a pipe.
 256 .TP
 257 .BR \-q [\f2rev\fP]
 258 quiet mode; diagnostics are not printed.
 259 .TP
 260 .BR \-I [\f2rev\fP]
 261 interactive mode;
 262 the user is prompted and questioned
 263 even if the standard input is not a terminal.
 264 .TP
 265 .BI \-d date
 266 retrieves the latest revision on the selected branch whose checkin date/time is
 267 less than or equal to
 268 .IR date .
 269 The date and time can be given in free format.
 270 The time zone
 271 .B LT
 272 stands for local time;
 273 other common time zone names are understood.
 274 For example, the following
 275 .IR date s
 276 are equivalent
 277 if local time is January 11, 1990, 8pm Pacific Standard Time,
 278 eight hours west of Coordinated Universal Time (\*u):
 279 .RS
 280 .LP
 281 .RS
 282 .nf
 283 .ta \w'\f3Thu, 11 Jan 1990 20:00:00 \-0800\fP  'u
 284 .ne 10
 285 \f38:00 pm lt\fP
 286 \f34:00 AM, Jan. 12, 1990\fP    default is \*u
 287 \f31990-01-12 04:00:00+00\fP    \*i 8601 (\*u)
 288 \f31990-01-11 20:00:00\-08\fP   \*i 8601 (local time)
 289 \f31990/01/12 04:00:00\fP       traditional \*r format
 290 \f3Thu Jan 11 20:00:00 1990 LT\fP       output of \f3ctime\fP(3) + \f3LT\fP
 291 \f3Thu Jan 11 20:00:00 PST 1990\fP      output of \f3date\fP(1)
 292 \f3Fri Jan 12 04:00:00 GMT 1990\fP
 293 \f3Thu, 11 Jan 1990 20:00:00 \-0800\fP  Internet RFC 822
 294 \f312-January-1990, 04:00 WET\fP
 295 .ta 4n +4n +4n +4n
 296 .fi
 297 .RE
 298 .LP
 299 Most fields in the date and time can be defaulted.
 300 The default time zone is normally \*u, but this can be overridden by the
 301 .B \-z
 302 option.
 303 The other defaults are determined in the order year, month, day,
 304 hour, minute, and second (most to least significant).  At least one of these
 305 fields must be provided.  For omitted fields that are of higher significance
 306 than the highest provided field, the time zone's current values are assumed.
 307 For all other omitted fields,
 308 the lowest possible values are assumed.
 309 For example, without
 310 .BR \-z ,
 311 the date
 312 .B "20, 10:30"
 313 defaults to
 314 10:30:00 \*u of the 20th of the \*u time zone's current month and year.
 315 The date/time must be quoted if it contains spaces.
 316 .RE
 317 .TP
 318 .BR \-M [\f2rev\fP]
 319 Set the modification time on the new working file
 320 to be the date of the retrieved revision.
 321 Use this option with care; it can confuse
 322 .BR make (1).
 323 .TP
 324 .BI \-s state
 325 retrieves the latest revision on the selected branch whose state is set to
 326 .IR state .
 327 .TP
 328 .B \-T
 329 Preserve the modification time on the \*r file
 330 even if the \*r file changes because a lock is added or removed.
 331 This option can suppress extensive recompilation caused by a
 332 .BR make (1)
 333 dependency of some other copy of the working file on the \*r file.
 334 Use this option with care; it can suppress recompilation even when it is needed,
 335 i.e. when the change of lock
 336 would mean a change to keyword strings in the other working file.
 337 .TP
 338 .BR \-w [\f2login\fP]
 339 retrieves the latest revision on the selected branch which was checked in
 340 by the user with login name
 341 .IR login .
 342 If the argument
 343 .I login
 344 is
 345 omitted, the caller's login is assumed.
 346 .TP
 347 .BI \-j joinlist
 348 generates a new revision which is the join of the revisions on
 349 .IR joinlist .
 350 This option is largely obsoleted by
 351 .BR rcsmerge (1)
 352 but is retained for backwards compatibility.
 353 .RS
 354 .PP
 355 The
 356 .I joinlist
 357 is a comma-separated list of pairs of the form
 358 .IB rev2 : rev3,
 359 where
 360 .I rev2
 361 and
 362 .I rev3
 363 are (symbolic or numeric)
 364 revision numbers.
 365 For the initial such pair,
 366 .I rev1
 367 denotes the revision selected
 368 by the above options
 369 .BR \-f ,
 370 \&.\|.\|.,
 371 .BR \-w .
 372 For all other pairs,
 373 .I rev1
 374 denotes the revision generated by the previous pair.
 375 (Thus, the output
 376 of one join becomes the input to the next.)
 377 .PP
 378 For each pair,
 379 .B co
 380 joins revisions
 381 .I rev1
 382 and
 383 .I rev3
 384 with respect to
 385 .IR rev2 .
 386 This means that all changes that transform
 387 .I rev2
 388 into
 389 .I rev1
 390 are applied to a copy of
 391 .IR rev3 .
 392 This is particularly useful if
 393 .I rev1
 394 and
 395 .I rev3
 396 are the ends of two branches that have
 397 .I rev2
 398 as a common ancestor.  If
 399 .IR rev1 < rev2 < rev3
 400 on the same branch,
 401 joining generates a new revision which is like
 402 .I rev3,
 403 but with all changes that lead from
 404 .I rev1
 405 to
 406 .I rev2
 407 undone.
 408 If changes from
 409 .I rev2
 410 to
 411 .I rev1
 412 overlap with changes from
 413 .I rev2
 414 to
 415 .I rev3,
 416 .B co
 417 reports overlaps as described in
 418 .BR merge (1).
 419 .PP
 420 For the initial pair,
 421 .I rev2
 422 can be omitted.  The default is the common
 423 ancestor.
 424 If any of the arguments indicate branches, the latest revisions
 425 on those branches are assumed.
 426 The options
 427 .B \-l
 428 and
 429 .B \-u
 430 lock or unlock
 431 .IR rev1 .
 432 .RE
 433 .TP
 434 .BI \-V
 435 Print \*r's version number.
 436 .TP
 437 .BI \-V n
 438 Emulate \*r version
 439 .I n,
 440 where
 441 .I n
 442 can be
 443 .BR 3 ,
 444 .BR 4 ,
 445 or
 446 .BR 5 .
 447 This can be useful when interchanging \*r files with others who are
 448 running older versions of \*r.
 449 To see which version of \*r your correspondents are running, have them invoke
 450 .BR "rcs \-V" ;
 451 this works with newer versions of \*r.
 452 If it doesn't work, have them invoke
 453 .B rlog
 454 on an \*r file;
 455 if none of the first few lines of output contain the string
 456 .B branch:
 457 it is version 3;
 458 if the dates' years have just two digits, it is version 4;
 459 otherwise, it is version 5.
 460 An \*r file generated while emulating version 3 loses its default branch.
 461 An \*r revision generated while emulating version 4 or earlier has
 462 a time stamp that is off by up to 13 hours.
 463 A revision extracted while emulating version 4 or earlier contains
 464 abbreviated dates of the form
 465 .IB yy / mm / dd
 466 and can also contain different white space and line prefixes
 467 in the substitution for
 468 .BR $\&Log$ .
 469 .TP
 470 .BI \-x "suffixes"
 471 Use
 472 .I suffixes
 473 to characterize \*r files.
 474 See
 475 .BR ci (1)
 476 for details.
 477 .TP
 478 .BI \-z zone
 479 specifies the date output format in keyword substitution,
 480 and specifies the default time zone for
 481 .I date
 482 in the
 483 .BI \-d date
 484 option.
 485 The
 486 .I zone
 487 should be empty, a numeric \*u offset, or the special string
 488 .B LT
 489 for local time.
 490 The default is an empty
 491 .IR zone ,
 492 which uses the traditional \*r format of \*u without any time zone indication
 493 and with slashes separating the parts of the date;
 494 otherwise, times are output in \*i 8601 format with time zone indication.
 495 For example, if local time is January 11, 1990, 8pm Pacific Standard Time,
 496 eight hours west of \*u,
 497 then the time is output as follows:
 498 .RS
 499 .LP
 500 .RS
 501 .nf
 502 .ta \w'\f3\-z+05:30\fP  'u +\w'\f31990-01-11 09:30:00+05:30\fP  'u
 503 .ne 4
 504 \f2option\fP    \f2time output\fP
 505 \f3\-z\fP       \f31990/01/12 04:00:00\fP       \f2(default)\fP
 506 \f3\-zLT\fP     \f31990-01-11 20:00:00\-08\fP
 507 \f3\-z+05:30\fP \f31990-01-12 09:30:00+05:30\fP
 508 .ta 4n +4n +4n +4n
 509 .fi
 510 .RE
 511 .LP
 512 The
 513 .B \-z
 514 option does not affect dates stored in \*r files,
 515 which are always \*u.
 516 .RE
 517 .SH "KEYWORD SUBSTITUTION"
 518 Strings of the form
 519 .BI $ keyword $
 520 and
 521 .BI $ keyword : .\|.\|. $
 522 embedded in
 523 the text are replaced
 524 with strings of the form
 525 .BI $ keyword : value $
 526 where
 527 .I keyword
 528 and
 529 .I value
 530 are pairs listed below.
 531 Keywords can be embedded in literal strings
 532 or comments to identify a revision.
 533 .PP
 534 Initially, the user enters strings of the form
 535 .BI $ keyword $ .
 536 On checkout,
 537 .B co
 538 replaces these strings with strings of the form
 539 .BI $ keyword : value $ .
 540 If a revision containing strings of the latter form
 541 is checked back in, the value fields will be replaced during the next
 542 checkout.
 543 Thus, the keyword values are automatically updated on checkout.
 544 This automatic substitution can be modified by the
 545 .B \-k
 546 options.
 547 .PP
 548 Keywords and their corresponding values:
 549 .TP
 550 .B $\&Author$
 551 The login name of the user who checked in the revision.
 552 .TP
 553 .B $\&Date$
 554 The date and time the revision was checked in.
 555 With
 556 .BI \-z zone
 557 a numeric time zone offset is appended; otherwise, the date is \*u.
 558 .TP
 559 .B $\&Header$
 560 A standard header containing the full pathname of the \*r file, the
 561 revision number, the date and time, the author, the state,
 562 and the locker (if locked).
 563 With
 564 .BI \-z zone
 565 a numeric time zone offset is appended to the date; otherwise, the date is \*u.
 566 .TP
 567 .B $\&Id$
 568 Same as
 569 .BR $\&Header$ ,
 570 except that the \*r filename is without a path.
 571 .TP
 572 .B $\&Locker$
 573 The login name of the user who locked the revision (empty if not locked).
 574 .TP
 575 .B $\&Log$
 576 The log message supplied during checkin, preceded by a header
 577 containing the \*r filename, the revision number, the author, and the date
 578 and time.
 579 With
 580 .BI \-z zone
 581 a numeric time zone offset is appended; otherwise, the date is \*u.
 582 Existing log messages are
 583 .I not
 584 replaced.
 585 Instead, the new log message is inserted after
 586 .BR $\&Log: .\|.\|. $ .
 587 This is useful for
 588 accumulating a complete change log in a source file.
 589 .RS
 590 .LP
 591 Each inserted line is prefixed by the string that prefixes the
 592 .B $\&Log$
 593 line.  For example, if the
 594 .B $\&Log$
 595 line is
 596 .RB \*(lq "//\ $\&Log: tan.cc\ $" \*(rq,
 597 \*r prefixes each line of the log with
 598 .RB \*(lq "//\ " \*(rq.
 599 This is useful for languages with comments that go to the end of the line.
 600 The convention for other languages is to use a
 601 .RB \*(lq " \(** " \(rq
 602 prefix inside a multiline comment.
 603 For example, the initial log comment of a C program
 604 conventionally is of the following form:
 605 .RS
 606 .LP
 607 .nf
 608 .ft 3
 609 .ne 3
 610 /\(**
 611 .in +\w'/'u
 612 \(** $\&Log$
 613 \(**/
 614 .in
 615 .ft
 616 .fi
 617 .RE
 618 .LP
 619 For backwards compatibility with older versions of \*r, if the log prefix is
 620 .B /\(**
 621 or
 622 .B (\(**
 623 surrounded by optional white space, inserted log lines contain a space
 624 instead of
 625 .B /
 626 or
 627 .BR ( ;
 628 however, this usage is obsolescent and should not be relied on.
 629 .RE
 630 .TP
 631 .B $\&Name$
 632 The symbolic name used to check out the revision, if any.
 633 For example,
 634 .B "co\ \-rJoe"
 635 generates
 636 .BR "$\&Name:\ Joe\ $" .
 637 Plain
 638 .B co
 639 generates just
 640 .BR "$\&Name:\ \ $" .
 641 .TP
 642 .B $\&RCSfile$
 643 The name of the \*r file without a path.
 644 .TP
 645 .B $\&Revision$
 646 The revision number assigned to the revision.
 647 .TP
 648 .B $\&Source$
 649 The full pathname of the \*r file.
 650 .TP
 651 .B $\&State$
 652 The state assigned to the revision with the
 653 .B \-s
 654 option of
 655 .BR rcs (1)
 656 or
 657 .BR ci (1).
 658 .PP
 659 The following characters in keyword values are represented by escape sequences
 660 to keep keyword strings well-formed.
 661 .LP
 662 .RS
 663 .nf
 664 .ne 6
 665 .ta \w'newline  'u
 666 \f2char escape sequence\fP
 667 tab     \f3\et\fP
 668 newline \f3\en\fP
 669 space   \f3\e040
 670 $       \e044
 671 \e      \e\e\fP
 672 .fi
 673 .RE
 674 .SH "FILE MODES"
 675 The working file inherits the read and execute permissions from the \*r
 676 file.  In addition, the owner write permission is turned on, unless
 677 .B \-kv
 678 is set or the file
 679 is checked out unlocked and locking is set to strict (see
 680 .BR rcs (1)).
 681 .PP
 682 If a file with the name of the working file exists already and has write
 683 permission,
 684 .B co
 685 aborts the checkout,
 686 asking beforehand if possible.
 687 If the existing working file is
 688 not writable or
 689 .B \-f
 690 is given, the working file is deleted without asking.
 691 .SH FILES
 692 .B co
 693 accesses files much as
 694 .BR ci (1)
 695 does, except that it does not need to read the working file
 696 unless a revision number of
 697 .B $
 698 is specified.
 699 .SH ENVIRONMENT
 700 .TP
 701 .B \s-1RCSINIT\s0
 702 options prepended to the argument list, separated by spaces.
 703 See
 704 .BR ci (1)
 705 for details.
 706 .SH DIAGNOSTICS
 707 The \*r pathname, the working pathname,
 708 and the revision number retrieved are
 709 written to the diagnostic output.
 710 The exit status is zero if and only if all operations were successful.
 711 .SH IDENTIFICATION
 712 Author: Walter F. Tichy.
 713 .br
 714 Manual Page Revision: \*(Rv; Release Date: \*(Dt.
 715 .br
 716 Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
 717 .br
 718 Copyright \(co 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert.
 719 .SH "SEE ALSO"
 720 rcsintro(1), ci(1), ctime(3), date(1), ident(1), make(1),
 721 rcs(1), rcsclean(1), rcsdiff(1), rcsmerge(1), rlog(1),
 722 rcsfile(5)
 723 .br
 724 Walter F. Tichy,
 725 \*r\*-A System for Version Control,
 726 .I "Software\*-Practice & Experience"
 727 .BR 15 ,
 728 7 (July 1985), 637-654.
 729 .SH LIMITS
 730 Links to the \*r and working files are not preserved.
 731 .PP
 732 There is no way to selectively suppress the expansion of keywords, except
 733 by writing them differently.  In nroff and troff, this is done by embedding the
 734 null-character
 735 .B \e&
 736 into the keyword.
 737 .br