home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 317a.lha / RCS / doc / co.1l.doc < prev    next >
Text File  |  1989-12-05  |  15KB  |  397 lines
  1.  
  2.  
  3.  
  4. CO(1L)            UNKNOWN SECTION OF THE MANUAL            CO(1L)
  5.  
  6.  
  7.  
  8. NAME
  9.      co - check out RCS revisions
  10.  
  11. SYNOPSIS
  12.      co [ options ] file ...
  13.  
  14. DESCRIPTION
  15.      _C_o retrieves a revision from each RCS  file  and  stores  it
  16.      into  the corresponding working file.  Each file name ending
  17.      in `,v' is taken to be an RCS  file;  all  other  files  are
  18.      assumed  to  be  working  files.   If only a working file is
  19.      given, _c_o tries to find the corresponding RCS  file  in  the
  20.      directory ./RCS and then in the current directory.  For more
  21.      details, see the file naming section below.
  22.  
  23.      Revisions of an RCS  file  may  be  checked  out  locked  or
  24.      unlocked. Locking a revision prevents overlapping updates. A
  25.      revision checked out for reading or processing  (e.g.,  com-
  26.      piling) need not be locked. A revision checked out for edit-
  27.      ing and later checkin must normally be locked. _C_o with lock-
  28.      ing  fails  if  the  revision to be checked out is currently
  29.      locked by another user.  (A lock  may  be  broken  with  the
  30.      _r_c_s(1L)  command.)  _C_o with locking also requires the caller
  31.      to be on the access list of the RCS file, unless he  is  the
  32.      owner  of  the  file or the superuser, or the access list is
  33.      empty.  _C_o without locking is not subject to accesslist res-
  34.      trictions, and is not affected by the presence of locks.
  35.  
  36.      A revision is selected by options  for  revision  or  branch
  37.      number,  checkin  date/time,  author,  or  state.   When the
  38.      selection options are applied in combination,  _c_o  retrieves
  39.      the  latest revision that satisfies all of them.  If none of
  40.      the selection options is specified, _c_o retrieves the  latest
  41.      revision  on the default branch (normally the trunk, see the
  42.      -b option of _r_c_s(1L)).  A revision or branch number  may  be
  43.      attached  to  any  of the options -f, -l, -p, -q, -r, or -u.
  44.      The options -d (date), -s (state), and -w (author)  retrieve
  45.      from  a  single branch, the _s_e_l_e_c_t_e_d branch, which is either
  46.      specified by one of -f,..., -u, or the default branch.
  47.  
  48.      A _c_o command applied  to  an  RCS  file  with  no  revisions
  49.      creates a zero-length working file.  _C_o always performs key-
  50.      word substitution (see below).
  51.  
  52.      -r[_r_e_v]    retrieves the latest  revision  whose  number  is
  53.                 less  than  or  equal to _r_e_v.  If _r_e_v indicates a
  54.                 branch rather than a revision, the  latest  revi-
  55.                 sion  on  that  branch  is  retrieved.  If _r_e_v is
  56.                 omitted,  the  latest  revision  on  the  default
  57.                 branch   (see   the  -b  option  of  _r_c_s(1L))  is
  58.                 retrieved.   _R_e_v  is  composed  of  one  or  more
  59.                 numeric  or symbolic fields separated by `.'. The
  60.  
  61.  
  62.  
  63. Purdue University         Last change:                          1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CO(1L)            UNKNOWN SECTION OF THE MANUAL            CO(1L)
  71.  
  72.  
  73.  
  74.                 numeric equivalent of a symbolic field is  speci-
  75.                 fied  with  the  -n option of the commands _c_i(1L)
  76.                 and _r_c_s(1L).
  77.  
  78.      -l[_r_e_v]    same  as  -r,  except  that  it  also  locks  the
  79.                 retrieved revision for the caller.  See option -r
  80.                 for handling of the revision number _r_e_v .
  81.  
  82.      -u[_r_e_v]    same as -r, except that it unlocks the  retrieved
  83.                 revision (if it was locked by the caller). If _r_e_v
  84.                 is omitted,  -u  retrieves  the  latest  revision
  85.                 locked  by the caller; if no such lock exists, it
  86.                 retrieves the  latest  revision  on  the  default
  87.                 branch.
  88.  
  89.      -f[_r_e_v]    forces the overwriting of the working file;  use-
  90.                 ful  in connection with -q.  See also the section
  91.                 on file modes below.
  92.  
  93.      -p[_r_e_v]    prints the retrieved  revision  on  the  standard
  94.                 output  rather  than  storing  it  in the working
  95.                 file.  This option is useful when _c_o is part of a
  96.                 pipe.
  97.  
  98.      -q[_r_e_v]    quiet mode; diagnostics are not printed.
  99.  
  100.      -d_d_a_t_e     retrieves the latest  revision  on  the  selected
  101.                 branch  whose  checkin  date/time is less than or
  102.                 equal to _d_a_t_e.  The date and time may be given in
  103.                 free  format  and  are  converted  to local time.
  104.                 Examples of formats for _d_a_t_e:
  105.  
  106.                 _2_2-_A_p_r_i_l-_1_9_8_2, _1_7:_2_0-_C_D_T,
  107.                 _2:_2_5 _A_M, _D_e_c. _2_9, _1_9_8_3,
  108.                 _T_u_e-_P_D_T, _1_9_8_1, _4_p_m _J_u_l _2_1         (free format),
  109.                 _F_r_i, _A_p_r_i_l _1_6 _1_5:_5_2:_2_5 _E_S_T _1_9_8_2 (output of ctime).
  110.  
  111.                 Most  fields  in  the  date  and  time   may   be
  112.                 defaulted.   _C_o  determines  the  defaults in the
  113.                 order year, month, day, hour, minute, and  second
  114.                 (most  to  least  significant).  At  least one of
  115.                 these fields must be provided. For omitted fields
  116.                 that  are of higher significance than the highest
  117.                 provided field, the current values  are  assumed.
  118.                 For all other omitted fields, the lowest possible
  119.                 values are assumed.  For example, the  date  "20,
  120.                 10:30"  defaults  to  10:30:00 of the 20th of the
  121.                 current month and current  year.   The  date/time
  122.                 must be quoted if it contains spaces.
  123.  
  124.      -s_s_t_a_t_e    retrieves the latest  revision  on  the  selected
  125.                 branch whose state is set to _s_t_a_t_e.
  126.  
  127.  
  128.  
  129. Purdue University         Last change:                          2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CO(1L)            UNKNOWN SECTION OF THE MANUAL            CO(1L)
  137.  
  138.  
  139.  
  140.      -w[_l_o_g_i_n]  retrieves the latest  revision  on  the  selected
  141.                 branch  which  was  checked  in  by the user with
  142.                 login name _l_o_g_i_n. If the argument _l_o_g_i_n is  omit-
  143.                 ted, the caller's login is assumed.
  144.  
  145.      -j_j_o_i_n_l_i_s_t generates a new revision which is the join of the
  146.                 revisions  on  _j_o_i_n_l_i_s_t.   _J_o_i_n_l_i_s_t  is  a comma-
  147.                 separated list of pairs of  the  form  _r_e_v_2:_r_e_v_3,
  148.                 where  _r_e_v_2  and  _r_e_v_3  are (symbolic or numeric)
  149.                 revision numbers.  For  the  initial  such  pair,
  150.                 _r_e_v_1  denotes  the revision selected by the above
  151.                 options -r, ..., -w. For all  other  pairs,  _r_e_v_1
  152.                 denotes  the  revision  generated by the previous
  153.                 pair. (Thus, the output of one join  becomes  the
  154.                 input to the next.)
  155.  
  156.                 For each pair, _c_o joins revisions _r_e_v_1  and  _r_e_v_3
  157.                 with  respect  to  _r_e_v_2.   This  means  that  all
  158.                 changes that transform _r_e_v_2 into _r_e_v_1 are applied
  159.                 to  a  copy of _r_e_v_3.  This is particularly useful
  160.                 if _r_e_v_1 and _r_e_v_3 are the  ends  of  two  branches
  161.                 that  have  _r_e_v_2  as a common ancestor. If _r_e_v_1 <
  162.                 _r_e_v_2 < _r_e_v_3 on the same branch, joining generates
  163.                 a  new  revision which is like _r_e_v_3, but with all
  164.                 changes that lead from _r_e_v_1 to _r_e_v_2  undone.   If
  165.                 changes  from  _r_e_v_2  to _r_e_v_1 overlap with changes
  166.                 from _r_e_v_2  to  _r_e_v_3,  _c_o  prints  a  warning  and
  167.                 includes  the  overlapping sections, delimited by
  168.                 the    lines    <<<<<<< _r_e_v_1,    =======,     and
  169.                 >>>>>>> _r_e_v_3.
  170.  
  171.                 For the initial pair, _r_e_v_2 may  be  omitted.  The
  172.                 default  is  the  common ancestor.  If any of the
  173.                 arguments indicate branches, the latest revisions
  174.                 on  those  branches  are assumed.  The options -l
  175.                 and -u lock or unlock _r_e_v_1.
  176.  
  177. KEYWORD SUBSTITUTION
  178.      Strings of the form $_k_e_y_w_o_r_d$ and $_k_e_y_w_o_r_d:...$ embedded  in
  179.      the   text   are   replaced   with   strings   of  the  form
  180.      $_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 are pairs  listed
  181.      below.   Keywords may be embedded in literal strings or com-
  182.      ments to identify a revision.
  183.  
  184.      Initially, the user enters strings of  the  form  $_k_e_y_w_o_r_d$.
  185.      On  checkout,  _c_o replaces these strings with strings of the
  186.      form $_k_e_y_w_o_r_d: _v_a_l_u_e $. If a revision containing strings  of
  187.      the latter form is checked back in, the value fields will be
  188.      replaced during the next checkout.  Thus, the keyword values
  189.      are automatically updated on checkout.
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Purdue University         Last change:                          3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CO(1L)            UNKNOWN SECTION OF THE MANUAL            CO(1L)
  203.  
  204.  
  205.  
  206.      Keywords and their corresponding values:
  207.  
  208.      $Author$     The login name of the user who checked  in  the
  209.                   revision.
  210.  
  211.      $Date$       The date and time the revision was checked in.
  212.  
  213.      $Header$     A standard header containing the full  pathname
  214.                   of the RCS file, the revision number, the date,
  215.                   the author,  the  state,  and  the  locker  (if
  216.                   locked).
  217.  
  218.      $Id$         Same as $Header$, except that the RCS file name
  219.                   is without a path.
  220.  
  221.      $Locker$     The login name of the user who locked the revi-
  222.                   sion (empty if not locked).
  223.  
  224.      $Log$        The log message supplied during  checkin,  pre-
  225.                   ceded by a header containing the RCS file name,
  226.                   the revision number, the author, and the  date.
  227.                   Existing   log   messages   are  NOT  replaced.
  228.                   Instead, the new log message is inserted  after
  229.                   $_L_o_g:...$.   This  is useful for accumulating a
  230.                   complete change log in a source file.
  231.  
  232.      $RCSfile$    The name of the RCS file without path.
  233.  
  234.      $Revision$   The revision number assigned to the revision.
  235.  
  236.      $Source$     The full pathname of the RCS file.
  237.  
  238.      $State$      The state assigned to the revision with the  -s
  239.                   option of _r_c_s(1L) or _c_i(1L).
  240.  
  241.      Pairs of RCS files and working files may be specified  in  3
  242.      ways (see also the example section).
  243.  
  244.      1) Both the RCS file and the working file are given. The RCS
  245.      file  name  is  of the form _p_a_t_h_1/_w_o_r_k_f_i_l_e,_v and the working
  246.      file name is of the form _p_a_t_h_2/_w_o_r_k_f_i_l_e,  where  _p_a_t_h_1/  and
  247.      _p_a_t_h_2/  are (possibly different or empty) paths and _w_o_r_k_f_i_l_e
  248.      is a file name.
  249.  
  250.      2) Only the RCS file is given.  Then  the  working  file  is
  251.      created  in  the  current  directory and its name is derived
  252.      from the name of the RCS file by  removing  _p_a_t_h_1/  and  the
  253.      suffix ,_v.
  254.  
  255.      3) Only the working file is given.  Then _c_o looks for an RCS
  256.      file  of  the  form _p_a_t_h_2/_R_C_S/_w_o_r_k_f_i_l_e,_v or _p_a_t_h_2/_w_o_r_k_f_i_l_e,_v
  257.      (in this order).
  258.  
  259.  
  260.  
  261. Purdue University         Last change:                          4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CO(1L)            UNKNOWN SECTION OF THE MANUAL            CO(1L)
  269.  
  270.  
  271.  
  272.      If the RCS file is specified without a path in  1)  and  2),
  273.      then  _c_o looks for the RCS file first in the directory ./RCS
  274.      and then in the current directory.
  275.  
  276. EXAMPLES
  277.      Suppose the current directory contains a subdirectory  `RCS'
  278.      with  an  RCS  file `io.c,v'. Then all of the following com-
  279.      mands retrieve the latest  revision  from  `RCS/io.c,v'  and
  280.      store it into `io.c'.
  281.  
  282.           co  io.c;    co  RCS/io.c,v;   co  io.c,v;
  283.           co  io.c  RCS/io.c,v;    co  io.c  io.c,v;
  284.           co  RCS/io.c,v  io.c;    co  io.c,v  io.c;
  285.  
  286. FILE MODES
  287.      The working file inherits the read and  execute  permissions
  288.      from  the  RCS file. In addition, the owner write permission
  289.      is turned on, unless the file is checked  out  unlocked  and
  290.      locking is set to _s_t_r_i_c_t (see _r_c_s(1L)).
  291.  
  292.      If a file with the name of the working file  exists  already
  293.      and  has  write  permission, _c_o aborts the checkout if -q is
  294.      given, or asks whether to abort if -q is not given.  If  the
  295.      existing  working  file  is not writable or -f is given, the
  296.      working file is deleted without asking.
  297.  
  298. FILES
  299.      The caller of the command must have write permission in  the
  300.      working  directory,  read  permission  for the RCS file, and
  301.      either read permission (for reading) or  read/write  permis-
  302.      sion  (for  locking) in the directory which contains the RCS
  303.      file.
  304.  
  305.      A number of temporary files are created.  A  semaphore  file
  306.      is  created  in  the  directory  of  the RCS file to prevent
  307.      simultaneous update.
  308.  
  309. DIAGNOSTICS
  310.      The RCS file name, the working file name, and  the  revision
  311.      number  retrieved are written to the diagnostic output.  The
  312.      exit status always refers to the last file checked out,  and
  313.      is 0 if the operation was successful, 1 otherwise.
  314.  
  315. IDENTIFICATION
  316.      Author: Walter F. Tichy, Purdue University, West  Lafayette,
  317.      IN, 47907.
  318.      Revision Number: 1.4 ; Release Date: 89/05/02 .
  319.      Copyright c 1982, 1988, 1989 by Walter F. Tichy.
  320.  
  321. SEE ALSO
  322.      ci(1L),  ident(1L),  rcs(1L),   rcsdiff(1L),   rcsintro(1L),
  323.      rcsmerge(1L), rlog(1L), rcsfile(5L)
  324.  
  325.  
  326.  
  327. Purdue University         Last change:                          5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. CO(1L)            UNKNOWN SECTION OF THE MANUAL            CO(1L)
  335.  
  336.  
  337.  
  338.      Walter F. Tichy, "Design, Implementation, and Evaluation  of
  339.      a Revision Control System," in _P_r_o_c_e_e_d_i_n_g_s _o_f _t_h_e _6_t_h _I_n_t_e_r_-
  340.      _n_a_t_i_o_n_a_l _C_o_n_f_e_r_e_n_c_e _o_n _S_o_f_t_w_a_r_e  _E_n_g_i_n_e_e_r_i_n_g,  IEEE,  Tokyo,
  341.      Sept. 1982.
  342.  
  343. LIMITATIONS
  344.      The option -d  gets  confused  in  some  circumstances,  and
  345.      accepts  no  date before 1970.  Links to the RCS and working
  346.      files are not preserved.  There is no way  to  suppress  the
  347.      expansion  of  keywords, except by writing them differently.
  348.      In nroff and troff, this is  done  by  embedding  the  null-
  349.      character `\&' into the keyword.
  350.  
  351. BUGS
  352.      The option -j does not work for  files  that  contain  lines
  353.      with a single `.'.
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393. Purdue University         Last change:                          6
  394.  
  395.  
  396.  
  397.