home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 8 / CDASC08.ISO / VRAC / RCSDOC.ZIP / CO.TXT < prev    next >
Text File  |  1993-08-09  |  20KB  |  391 lines
  1.  
  2.  
  3. CO(1)                      Unix Programmer's Manual                      CO(1)
  4.  
  5.  
  6. NNNAAAMMMEEE
  7.      co - check out RCS revisions
  8.  
  9. SSSYYYNNNOOOPPPSSSIIISSS
  10.      cccooo [_o_p_t_i_o_n_s] _f_i_l_e ...
  11.  
  12. DDDEEESSSCCCRRRIIIPPPTTTIIIOOONNN
  13.      cccooo retrieves a revision from  each  RCS  file  and  stores  it  into  the
  14.      corresponding  working  file.  Each file name ending in ,,,vvv is taken to be
  15.      an RCS file; all other files are assumed to be working files.  If only  a
  16.      working file is given, cccooo tries to find the corresponding RCS file in the
  17.      directory ...///RRRCCCSSS and then in the current directory.  For more details, see
  18.      FILE NAMING below.
  19.  
  20.      Revisions of an RCS file may be checked out locked or unlocked.   Locking
  21.      a  revision  prevents  overlapping  updates.   A revision checked out for
  22.      reading or processing (e.g., compiling) need not be locked.   A  revision
  23.      checked  out  for  editing  and  later  checkin  must normally be locked.
  24.      Checkout with locking  fails  if  the  revision  to  be  checked  out  is
  25.      currently  locked  by another user.  (A lock may be broken with rrrcccsss(1).)\
  26.      Checkout with locking also requires the caller to be on the  access  list
  27.      of  the RCS file, unless he is the owner of the file or the superuser, or
  28.      the access list is empty.  Checkout without locking  is  not  subject  to
  29.      accesslist restrictions, and is not affected by the presence of locks.
  30.  
  31.      A revision is selected by options for revision or branch number,  checkin
  32.      date/time,  author,  or state.  When the selection options are applied in
  33.      combination, cccooo retrieves the latest revision that satisfies all of them.
  34.      If  none  of  the selection options is specified, cccooo retrieves the latest
  35.      revision on the default branch (normally the trunk, see the ---bbb option  of
  36.      rrrcccsss(1)).   A  revision  or  branch  number  may be attached to any of the
  37.      options ---fff, ---III, ---lll, ---ppp, ---qqq,  ---rrr,  or  ---uuu.   The  options  ---ddd  (date),  ---sss
  38.      (state),  and  ---www  (author)  retrieve  from a single branch, the _s_e_l_e_c_t_e_d
  39.      branch, which is either specified by one of ---fff,,, ..., ---uuu, or  the  default
  40.      branch.
  41.  
  42.      A cccooo command applied to an RCS file with no  revisions  creates  a  zero-
  43.      length  working  file.   cccooo  always  performs  keyword  substitution (see
  44.      below).
  45.  
  46. OOOPPPTTTIIIOOONNNSSS
  47.  
  48.      ---rrr[rev]]]
  49.           retrieves the latest revision whose number is less than or equal  to
  50.           _r_e_v.  If  _r_e_v  indicates a branch rather than a revision, the latest
  51.           revision on that branch is retrieved.  If _r_e_v is omitted, the latest
  52.           revision  on  the  default  branch  (see the ---bbb option of rrrcccsss(1)) is
  53.           retrieved.  A revision  is  composed  of  one  or  more  numeric  or
  54.           symbolic  fields  separated by periods.  The numeric equivalent of a
  55.           symbolic field is specified with the ---nnn option of the commands ccciii(1)
  56.           and rrrcccsss(1).
  57.  
  58.      ---lll[rev]]]
  59.           same as ---rrr, except that it also locks the retrieved revision for the
  60.           caller.
  61.  
  62.  
  63.  
  64.                                     \*(Dt                                    1
  65.  
  66.  
  67.  
  68. CO(1)                      Unix Programmer's Manual                      CO(1)
  69.  
  70.  
  71.      ---uuu[rev]]]
  72.           same as ---rrr, except that it unlocks the retrieved revision if it  was
  73.           locked  by  the  caller.  If _r_e_v is omitted, ---uuu retrieves the latest
  74.           revision locked by the caller; if no such lock exists, it  retrieves
  75.           the latest revision on the default branch.
  76.  
  77.      ---fff[rev]]]
  78.           forces the overwriting of the working  file;  useful  in  connection
  79.           with ---qqq.  See also FILE MODES below.
  80.  
  81.      ---kkkkkkvvv Generate keyword strings using the default form, e.g. $$$RRReeevvviiisssiiiooonnn::: 555...444
  82.           $$$  for  the  RRReeevvviiisssiiiooonnn  keyword.   A locker's name is inserted in the
  83.           value of the HHHeeeaaadddeeerrr, IIIddd, and LLLoooccckkkeeerrr keyword strings only as  a  file
  84.           is being locked, i.e. by ccciii\\\ ---lll and cccooo\\\ ---lll.  This is the default.
  85.  
  86.      ---kkkkkkvvvlll
  87.           Like ---kkkkkkvvv, except that a locker's name is  always  inserted  if  the
  88.           given revision is currently locked.
  89.  
  90.      ---kkkkkk  Generate only keyword names in keyword strings; omit  their  values.
  91.           See  KEYWORD  SUBSTITUTION  below.   For  example,  for the RRReeevvviiisssiiiooonnn
  92.           keyword, generate the string $$$RRReeevvviiisssiiiooonnn$$$ instead of $$$RRReeevvviiisssiiiooonnn::: 555...444 $$$.
  93.           This   option  is  useful  to  ignore  differences  due  to  keyword
  94.           substitution when comparing different revisions of a file.
  95.  
  96.      ---kkkooo  Generate the old keyword string, present in the  working  file  just
  97.           before  it  was  checked in.  For example, for the RRReeevvviiisssiiiooonnn keyword,
  98.           generate the string $$$RRReeevvviiisssiiiooonnn::: 111...111 $$$ instead of $$$RRReeevvviiisssiiiooonnn::: 555...444 $$$  if
  99.           that  is how the string appeared when the file was checked in.  This
  100.           can be useful for binary  file  formats  that  cannot  tolerate  any
  101.           changes  to  substrings  that  happen  to  take  the form of keyword
  102.           strings.
  103.  
  104.      ---kkkvvv  Generate only keyword values for keyword strings.  For example,  for
  105.           the  RRReeevvviiisssiiiooonnn keyword, generate the string 555...444 instead of $$$RRReeevvviiisssiiiooonnn:::
  106.           555...444 $$$.  This can help generate files in programming languages  where
  107.           it  is  hard  to  strip keyword delimiters like $$$RRReeevvviiisssiiiooonnn:::\\\ $$$ from a
  108.           string.  However, further keyword substitution cannot  be  performed
  109.           once  the  keyword  names are removed, so this option should be used
  110.           with care.  Because of this danger of losing keywords,  this  option
  111.           cannot  be  combined  with ---lll, and the owner write permission of the
  112.           working file is turned off; to edit the file  later,  check  it  out
  113.           again without ---kkkvvv.
  114.  
  115.      ---ppp[rev]]]
  116.           prints the retrieved revision on the  standard  output  rather  than
  117.           storing  it  in  the working file.  This option is useful when cccooo is
  118.           part of a pipe.
  119.  
  120.      ---qqq[rev]]]
  121.           quiet mode; diagnostics are not printed.
  122.  
  123.      ---III[rev]]]
  124.           interactive mode; the user is prompted and questioned  even  if  the
  125.           standard input is not a terminal.
  126.  
  127.  
  128.  
  129.                                     \*(Dt                                    2
  130.  
  131.  
  132.  
  133. CO(1)                      Unix Programmer's Manual                      CO(1)
  134.  
  135.  
  136.      ---ddd_d_a_t_e
  137.           retrieves the latest revision on the selected branch  whose  checkin
  138.           date/time  is  less  than or equal to _d_a_t_e. The date and time may be
  139.           given in free format.  The time zone LLLTTT stands for local time; other
  140.           common  time  zone names are understood.  For example, the following
  141.           _d_a_t_es are equivalent if local time is January 11, 1990, 8pm  Pacific
  142.           Standard Time (eight hours west of GMT):
  143.  
  144.           8:00 pm lt
  145.           4:00 AM, Jan. 12, 1990                  note: default is GMT
  146.           1990/01/12 04:00:00                     RCS date format
  147.           Thu Jan 11 20:00:00 1990 LT             output of ctime(3) + LT
  148.           Thu Jan 11 20:00:00 PST 1990            output of date(1)
  149.           Fri Jan 12 04:00:00 GMT 1990
  150.           Thu, 11 Jan 1990 20:00:00 -0800
  151.           Fri-JST, 1990, 1pm Jan 12
  152.           12-January-1990, 04:00-WET
  153.  
  154.      Most fields in the date and time may be defaulted.  The default time zone
  155.      is GMT.  The other defaults are determined in the order year, month, day,
  156.      hour, minute, and second (most to least significant).  At  least  one  of
  157.      these  fields  must  be  provided.  For omitted fields that are of higher
  158.      significance than the highest provided field,  the  time  zone's  current
  159.      values  are  assumed.   For all other omitted fields, the lowest possible
  160.      values are assumed.  For example, the date 222000,,, 111000:::333000 defaults to 10:30:00
  161.      GMT  of  the  20th  of  the  GMT time zone's current month and year.  The
  162.      date/time must be quoted if it contains spaces.
  163.  
  164.      ---sss_s_t_a_t_e
  165.           retrieves the latest revision on the selected branch whose state  is
  166.           set to _s_t_a_t_e.
  167.  
  168.      ---www[login]]]
  169.           retrieves the latest revision  on  the  selected  branch  which  was
  170.           checked  in by the user with login name _l_o_g_i_n. If the argument _l_o_g_i_n
  171.           is omitted, the caller's login is assumed.
  172.  
  173.      ---jjj_j_o_i_n_l_i_s_t
  174.           generates a new revision which is  the  join  of  the  revisions  on
  175.           _j_o_i_n_l_i_s_t.  This  option  is  largely obsoleted by rrrcccsssmmmeeerrrgggeee(1) but is
  176.           retained for backwards compatibility.
  177.  
  178.      The _j_o_i_n_l_i_s_t is a comma-separated list of pairs of  the  form  _r_e_v_2:::_r_e_v_3,
  179.      where  _r_e_v_2 and _r_e_v_3 are (symbolic or numeric) revision numbers.  For the
  180.      initial such pair, _r_e_v_1  denotes  the  revision  selected  by  the  above
  181.      options  ---fff,,,  ...,  ---www.   For  all other pairs, _r_e_v_1 denotes the revision
  182.      generated by the previous pair.  (Thus, the output of  one  join  becomes
  183.      the input to the next.)
  184.  
  185.      For each pair, cccooo joins revisions _r_e_v_1 and _r_e_v_3  with  respect  to  _r_e_v_2.
  186.      This  means that all changes that transform _r_e_v_2 into _r_e_v_1 are applied to
  187.      a copy of _r_e_v_3. This is particularly useful if _r_e_v_1 and _r_e_v_3 are the ends
  188.      of  two  branches that have _r_e_v_2 as a common ancestor.  If _r_e_v_1<_r_e_v_2<_r_e_v_3
  189.      on the same branch, joining generates a new revision which is like  _r_e_v_3,
  190.      but with all changes that lead from _r_e_v_1 to _r_e_v_2 undone.  If changes from
  191.      _r_e_v_2 to _r_e_v_1 overlap with changes from _r_e_v_2 to _r_e_v_3, cccooo prints a  warning
  192.  
  193.  
  194.                                     \*(Dt                                    3
  195.  
  196.  
  197.  
  198. CO(1)                      Unix Programmer's Manual                      CO(1)
  199.  
  200.  
  201.      and includes the overlapping sections, delimited by  the  lines  <<<<<<<<<<<<<<<<<<<<<\
  202.      _r_e_v_1, =====================, and >>>>>>>>>>>>>>>>>>>>>\ _r_e_v_3.
  203.  
  204.      For the initial pair, _r_e_v_2 may be omitted.  The  default  is  the  common
  205.      ancestor.   If  any  of  the  arguments  indicate  branches,  the  latest
  206.      revisions on those branches are assumed.  The options ---lll and ---uuu  lock  or
  207.      unlock _r_e_v_1.
  208.  
  209.      ---VVV_n  Emulate RCS version _n, where _n may be 333,  444,  or  555.   This  may  be
  210.           useful  when  interchanging  RCS  files  with others who are running
  211.           older  versions  of  RCS.   To  see  which  version  of   RCS   your
  212.           correspondents are running, have them invoke rrrllloooggg on an RCS file; if
  213.           none of the first few lines of output contain the string bbbrrraaannnccchhh:::  it
  214.           is  version  3;  if  the  dates'  years  have just two digits, it is
  215.           version 4; otherwise, it is version 5.  An RCS file generated  while
  216.           emulating  version  3 will lose its default branch.  An RCS revision
  217.           generated while emulating version 4 or earlier will have a timestamp
  218.           that is off by up to 13 hours.  A revision extracted while emulating
  219.           version 4 or earlier will contain dates of the form _y_y///_m_m///_d_d instead
  220.           of  _y_y_y_y///_m_m///_d_d  and  may  also  contain different white space in the
  221.           substitution for $$$LLLoooggg$$$.
  222.  
  223. KKKEEEYYYWWWOOORRRDDD SSSUUUBBBSSSTTTIIITTTUUUTTTIIIOOONNN
  224.      Strings of the form $$$_k_e_y_w_o_r_d$$$ and $$$_k_e_y_w_o_r_d:::...$$$ embedded in the text  are
  225.      replaced with strings of the form $$$_k_e_y_w_o_r_d:::_v_a_l_u_e$$$ where _k_e_y_w_o_r_d and _v_a_l_u_e
  226.      are pairs listed below.  Keywords may be embedded in literal  strings  or
  227.      comments to identify a revision.
  228.  
  229.      Initially, the user enters strings of the form $$$_k_e_y_w_o_r_d$$$.   On  checkout,
  230.      cccooo replaces these strings with strings of the form $$$_k_e_y_w_o_r_d:::_v_a_l_u_e$$$.  If a
  231.      revision containing strings of the latter form is checked  back  in,  the
  232.      value  fields  will  be  replaced  during  the  next checkout.  Thus, the
  233.      keyword values are automatically updated  on  checkout.   This  automatic
  234.      substitution can be modified by the ---kkk options.
  235.  
  236.      Keywords and their corresponding values:
  237.  
  238.      $$$AAAuuuttthhhooorrr$$$
  239.           The login name of the user who checked in the revision.
  240.  
  241.      $$$DDDaaattteee$$$
  242.           The date and time (GMT) the revision was checked in.
  243.  
  244.      $$$HHHeeeaaadddeeerrr$$$
  245.           A standard header containing the full pathname of the RCS file,  the
  246.           revision  number,  the  date  (GMT),  the author, the state, and the
  247.           locker (if locked).
  248.  
  249.      $$$IIIddd$$$ Same as $$$HHHeeeaaadddeeerrr$$$, except that the RCS file name is without a path.
  250.  
  251.      $$$LLLoooccckkkeeerrr$$$
  252.           The login name of the user who locked the  revision  (empty  if  not
  253.           locked).
  254.  
  255.  
  256.  
  257.  
  258.  
  259.                                     \*(Dt                                    4
  260.  
  261.  
  262.  
  263. CO(1)                      Unix Programmer's Manual                      CO(1)
  264.  
  265.  
  266.      $$$LLLoooggg$$$
  267.           The log message  supplied  during  checkin,  preceded  by  a  header
  268.           containing  the  RCS file name, the revision number, the author, and
  269.           the date (GMT).  Existing log messages are _n_o_t  replaced.   Instead,
  270.           the new log message is inserted after $$$LLLoooggg:::...$$$.  This is useful for
  271.           accumulating a complete change log in a source file.
  272.  
  273.      $$$RRRCCCSSSfffiiillleee$$$
  274.           The name of the RCS file without a path.
  275.  
  276.      $$$RRReeevvviiisssiiiooonnn$$$
  277.           The revision number assigned to the revision.
  278.  
  279.      $$$SSSooouuurrrccceee$$$
  280.           The full pathname of the RCS file.
  281.  
  282.      $$$SSStttaaattteee$$$
  283.           The state assigned to the revision with the ---sss option of  rrrcccsss(1)  or
  284.           ccciii(1).
  285.  
  286. FFFIIILLLEEE NNNAAAMMMIIINNNGGG
  287.      Pairs of RCS files and working files may be specified in three ways  (see
  288.      also the example section).
  289.  
  290.      1) Both the RCS file and the working file are given.  The RCS  file  name
  291.      is  of the form _p_a_t_h_1///_w_o_r_k_f_i_l_e,,,vvv and the working file name is of the form
  292.      _p_a_t_h_2///_w_o_r_k_f_i_l_e where _p_a_t_h_1/// and _p_a_t_h_2/// are (possibly different or  empty)
  293.      paths and _w_o_r_k_f_i_l_e is a file name.
  294.  
  295.      2) Only the RCS file is given.  Then the working file is created  in  the
  296.      current  directory  and its name is derived from the name of the RCS file
  297.      by removing _p_a_t_h_1/// and the suffix ,,,vvv.
  298.  
  299.      3) Only the working file is given.  Then cccooo looks for an RCS file of  the
  300.      form _p_a_t_h_2///RRRCCCSSS///_w_o_r_k_f_i_l_e,,,vvv or _p_a_t_h_2///_w_o_r_k_f_i_l_e,,,vvv (in this order).
  301.  
  302.      If the RCS file is specified without a path in 1) and 2), then  cccooo  looks
  303.      for  the  RCS  file  first in the directory ...///RRRCCCSSS and then in the current
  304.      directory.
  305.  
  306. EEEXXXAAAMMMPPPLLLEEESSS
  307.      Suppose the current directory contains a subdirectory  RRRCCCSSS  with  an  RCS
  308.      file  iiiooo...ccc,,,vvv.   Then  all  of  the following commands retrieve the latest
  309.      revision from RRRCCCSSS///iiiooo...ccc,,,vvv and store it into iiiooo...ccc.
  310.  
  311.           co  io.c;    co  RCS/io.c,v;   co  io.c,v;
  312.           co  io.c  RCS/io.c,v;    co  io.c  io.c,v;
  313.           co  RCS/io.c,v  io.c;    co  io.c,v  io.c;
  314.  
  315. FFFIIILLLEEE MMMOOODDDEEESSS
  316.      The working file inherits the read and execute permissions from  the  RCS
  317.      file.   In  addition, the owner write permission is turned on, unless ---kkkvvv
  318.      is set or the file is checked out unlocked and locking is set  to  strict
  319.      (see rrrcccsss(1)).
  320.  
  321.  
  322.  
  323.  
  324.                                     \*(Dt                                    5
  325.  
  326.  
  327.  
  328. CO(1)                      Unix Programmer's Manual                      CO(1)
  329.  
  330.  
  331.      If a file with the name of the working file exists already and has  write
  332.      permission,  cccooo  aborts  the checkout, asking beforehand if possible.  If
  333.      the existing working file is not writable or ---fff  is  given,  the  working
  334.      file is deleted without asking.
  335.  
  336. FFFIIILLLEEESSS
  337.      cccooo accesses files much as ccciii(1) does, except that it  does  not  need  to
  338.      read the working file.
  339.  
  340. DDDIIIAAAGGGNNNOOOSSSTTTIIICCCSSS
  341.      The RCS file name,  the  working  file  name,  and  the  revision  number
  342.      retrieved  are written to the diagnostic output.  The exit status is zero
  343.      if and only if all operations were successful.
  344.  
  345. IIIDDDEEENNNTTTIIIFFFIIICCCAAATTTIIIOOONNN
  346.      Author: Walter F. Tichy.
  347.      Revision Number: 5.4; Release Date: 1990/12/04.
  348.      Copyright (c) 1982, 1988, 1989 by Walter F. Tichy.
  349.      Copyright (c) 1990 by Paul Eggert.
  350.  
  351. SSSEEEEEE AAALLLSSSOOO
  352.      ci(1), ctime(3),  date(1),  ident(1),  rcs(1),  rcsdiff(1),  rcsintro(1),
  353.      rcsmerge(1), rlog(1), rcsfile(5)
  354.      Walter F. Tichy, RCS--A System for Version Control, _S_o_f_t_w_a_r_e--_P_r_a_c_t_i_c_e  &
  355.      _E_x_p_e_r_i_e_n_c_e 111555, 7 (July 1985), 637-654.
  356.  
  357. LLLIIIMMMIIITTTSSS
  358.      Links to the RCS and working files are not preserved.
  359.  
  360.      There is no way to selectively suppress the expansion of keywords, except
  361.      by  writing  them  differently.   In  nroff  and  troff,  this is done by
  362.      embedding the null-character \\\&&& into the keyword.
  363.  
  364. BBBUUUGGGSSS
  365.      The ---ddd option sometimes gets confused, and accepts no date before 1970.
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.                                     \*(Dt                                    6
  390.  
  391.