home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 22 gnu / 22-gnu.zip / rcs57pc1.zip / doc / co.man < prev    next >
Text File  |  1996-02-13  |  23KB  |  595 lines

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