home *** CD-ROM | disk | FTP | other *** search
/ Borland Programmer's Resource / Borland_Programmers_Resource_CD_1995.iso / utils / gr564b / co.1 < prev    next >
Text File  |  1995-05-18  |  19KB  |  463 lines
  1.  
  2.  
  3.  
  4. CO(1)                                                       CO(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        co - check out RCS revisions
  9.  
  10. SSYYNNOOPPSSIISS
  11.        ccoo [_o_p_t_i_o_n_s] _f_i_l_e ...
  12.  
  13. DDEESSCCRRIIPPTTIIOONN
  14.        ccoo 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 ccii(1).
  20.  
  21.        Revisions of an RCS file may 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 may be
  28.        broken with rrccss(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, ccoo retrieves
  38.        the latest revision that satisfies all of them.  If none
  39.        of the selection options is specified, ccoo retrieves the
  40.        latest revision on the default branch (normally the trunk,
  41.        see the --bb option of rrccss(1)).  A revision or branch number
  42.        may be attached to any of the options --ff, --II, --ll, --MM, --pp,
  43.        --qq, --rr, or --uu.  The options --dd (date), --ss (state), and --ww
  44.        (author) retrieve from a single branch, the _s_e_l_e_c_t_e_d
  45.        branch, which is either specified by one of --ff,, ..., --uu,
  46.        or the default branch.
  47.  
  48.        A ccoo command applied to an RCS file with no revisions
  49.        creates a zero-length working file.  ccoo always performs
  50.        keyword substitution (see below).
  51.  
  52. OOPPTTIIOONNSS
  53.        --rr[_r_e_v]
  54.               retrieves the latest revision whose number is less
  55.               than or equal to _r_e_v.  If _r_e_v indicates a branch
  56.               rather than a revision, the latest revision on that
  57.               branch is retrieved.  If _r_e_v is omitted, the latest
  58.               revision on the default branch (see the --bb option
  59.               of rrccss(1)) is retrieved.  If _r_e_v is $$, ccoo
  60.               determines the revision number from keyword values
  61.  
  62.  
  63.  
  64. GNU                         1992/07/28                          1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CO(1)                                                       CO(1)
  71.  
  72.  
  73.               in the working file.  Otherwise, a revision is
  74.               composed of one or more numeric or symbolic fields
  75.               separated by periods.  The numeric equivalent of a
  76.               symbolic field is specified with the --nn option of
  77.               the commands ccii(1) and rrccss(1).
  78.  
  79.        --ll[_r_e_v]
  80.               same as --rr, except that it also locks the retrieved
  81.               revision for the caller.
  82.  
  83.        --uu[_r_e_v]
  84.               same as --rr, except that it unlocks the retrieved
  85.               revision if it was locked by the caller.  If _r_e_v is
  86.               omitted, --uu retrieves the revision locked by the
  87.               caller, if there is one; otherwise, it retrieves
  88.               the latest revision on the default branch.
  89.  
  90.        --ff[_r_e_v]
  91.               forces the overwriting of the working file; useful
  92.               in connection with --qq.  See also FILE MODES below.
  93.  
  94.        --kkkkvv   Generate keyword strings using the default form,
  95.               e.g. $$RReevviissiioonn:: 55..99 $$ for the RReevviissiioonn keyword.  A
  96.               locker's name is inserted in the value of the
  97.               HHeeaaddeerr, IIdd, and LLoocckkeerr keyword strings only as a
  98.               file is being locked, i.e. by ccii --ll and ccoo --ll.
  99.               This is the default.
  100.  
  101.        --kkkkvvll  Like --kkkkvv, except that a locker's name is always
  102.               inserted if the given revision is currently locked.
  103.  
  104.        --kkkk    Generate only keyword names in keyword strings;
  105.               omit their values.  See KEYWORD SUBSTITUTION below.
  106.               For example, for the RReevviissiioonn keyword, generate the
  107.               string $$RReevviissiioonn$$ instead of $$RReevviissiioonn:: 55..99 $$.
  108.               This option is useful to ignore differences due to
  109.               keyword substitution when comparing different
  110.               revisions of a file.
  111.  
  112.        --kkoo    Generate the old keyword string, present in the
  113.               working file just before it was checked in.  For
  114.               example, for the RReevviissiioonn keyword, generate the
  115.               string $$RReevviissiioonn:: 11..11 $$ instead of $$RReevviissiioonn:: 55..99 $$
  116.               if that is how the string appeared when the file
  117.               was checked in.  This can be useful for binary file
  118.               formats that cannot tolerate any changes to
  119.               substrings that happen to take the form of keyword
  120.               strings.
  121.  
  122.        --kkvv    Generate only keyword values for keyword strings.
  123.               For example, for the RReevviissiioonn keyword, generate the
  124.               string 55..99 instead of $$RReevviissiioonn:: 55..99 $$.  This can
  125.               help generate files in programming languages where
  126.               it is hard to strip keyword delimiters like
  127.  
  128.  
  129.  
  130. GNU                         1992/07/28                          2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CO(1)                                                       CO(1)
  137.  
  138.  
  139.               $$RReevviissiioonn:: $$ from a string.  However, further
  140.               keyword substitution cannot be performed once the
  141.               keyword names are removed, so this option should be
  142.               used with care.  Because of this danger of losing
  143.               keywords, this option cannot be combined with --ll,
  144.               and the owner write permission of the working file
  145.               is turned off; to edit the file later, check it out
  146.               again without --kkvv.
  147.  
  148.        --pp[_r_e_v]
  149.               prints the retrieved revision on the standard
  150.               output rather than storing it in the working file.
  151.               This option is useful when ccoo is part of a pipe.
  152.  
  153.        --qq[_r_e_v]
  154.               quiet mode; diagnostics are not printed.
  155.  
  156.        --II[_r_e_v]
  157.               interactive mode; the user is prompted and
  158.               questioned even if the standard input is not a
  159.               terminal.
  160.  
  161.        --dd_d_a_t_e retrieves the latest revision on the selected
  162.               branch whose checkin date/time is less than or
  163.               equal to _d_a_t_e.  The date and time may be given in
  164.               free format.  The time zone LLTT stands for local
  165.               time; other common time zone names are understood.
  166.               For example, the following _d_a_t_es are equivalent if
  167.               local time is January 11, 1990, 8pm Pacific
  168.               Standard Time, eight hours west of Coordinated
  169.               Universal Time (UTC):
  170.  
  171.                      88::0000 ppmm lltt
  172.                      44::0000 AAMM,, JJaann.. 1122,, 11999900           note: default is UTC
  173.                      11999900//0011//1122 0044::0000::0000              RCS date format
  174.                      TThhuu JJaann 1111 2200::0000::0000 11999900 LLTT      output of ccttiimmee(3) + LLTT
  175.                      TThhuu JJaann 1111 2200::0000::0000 PPSSTT 11999900     output of ddaattee(1)
  176.                      FFrrii JJaann 1122 0044::0000::0000 GGMMTT 11999900
  177.                      TThhuu,, 1111 JJaann 11999900 2200::0000::0000 --00880000
  178.                      FFrrii--JJSSTT,, 11999900,, 11ppmm JJaann 1122
  179.                      1122--JJaannuuaarryy--11999900,, 0044::0000--WWEETT
  180.  
  181.               Most fields in the date and time may be defaulted.
  182.               The default time zone is UTC.  The other defaults
  183.               are determined in the order year, month, day, hour,
  184.               minute, and second (most to least significant).  At
  185.               least one of these fields must be provided.  For
  186.               omitted fields that are of higher significance than
  187.               the highest provided field, the time zone's current
  188.               values are assumed.  For all other omitted fields,
  189.               the lowest possible values are assumed.  For
  190.               example, the date 2200,, 1100::3300 defaults to 10:30:00
  191.               UTC of the 20th of the UTC time zone's current
  192.               month and year.  The date/time must be quoted if it
  193.  
  194.  
  195.  
  196. GNU                         1992/07/28                          3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CO(1)                                                       CO(1)
  203.  
  204.  
  205.               contains spaces.
  206.  
  207.        --MM[_r_e_v]
  208.               Set the modification time on the new working file
  209.               to be the date of the retrieved revision.  Use this
  210.               option with care; it can confuse mmaakkee(1).
  211.  
  212.        --ss_s_t_a_t_e
  213.               retrieves the latest revision on the selected
  214.               branch whose state is set to _s_t_a_t_e.
  215.  
  216.        --TT     Preserve the modification time on the RCS file even
  217.               if the RCS file changes because a lock is added or
  218.               removed.  This option can suppress extensive
  219.               recompilation caused by a mmaakkee(1) dependency of
  220.               some other copy of the working file on the RCS
  221.               file.  Use this option with care; it can suppress
  222.               recompilation even when it is needed, i.e. when the
  223.               change of lock would mean a change to keyword
  224.               strings in the other working file.
  225.  
  226.        --ww[_l_o_g_i_n]
  227.               retrieves the latest revision on the selected
  228.               branch which was checked in by the user with login
  229.               name _l_o_g_i_n.  If the argument _l_o_g_i_n is omitted, the
  230.               caller's login is assumed.
  231.  
  232.        --jj_j_o_i_n_l_i_s_t
  233.               generates a new revision which is the join of the
  234.               revisions on _j_o_i_n_l_i_s_t.  This option is largely
  235.               obsoleted by rrccssmmeerrggee(1) but is retained for
  236.               backwards compatibility.
  237.  
  238.               The _j_o_i_n_l_i_s_t is a comma-separated list of pairs of
  239.               the form _r_e_v_2::_r_e_v_3_, where _r_e_v_2 and _r_e_v_3 are
  240.               (symbolic or numeric) revision numbers.  For the
  241.               initial such pair, _r_e_v_1 denotes the revision
  242.               selected by the above options --ff,, ..., --ww.  For all
  243.               other pairs, _r_e_v_1 denotes the revision generated by
  244.               the previous pair.  (Thus, the output of one join
  245.               becomes the input to the next.)
  246.  
  247.               For each pair, ccoo joins revisions _r_e_v_1 and _r_e_v_3
  248.               with respect to _r_e_v_2.  This means that all changes
  249.               that transform _r_e_v_2 into _r_e_v_1 are applied to a copy
  250.               of _r_e_v_3.  This is particularly useful if _r_e_v_1 and
  251.               _r_e_v_3 are the ends of two branches that have _r_e_v_2 as
  252.               a common ancestor.  If _r_e_v_1<_r_e_v_2<_r_e_v_3 on the same
  253.               branch, joining generates a new revision which is
  254.               like _r_e_v_3_, but with all changes that lead from _r_e_v_1
  255.               to _r_e_v_2 undone.  If changes from _r_e_v_2 to _r_e_v_1
  256.               overlap with changes from _r_e_v_2 to _r_e_v_3_, ccoo reports
  257.               overlaps as described in mmeerrggee(1).
  258.  
  259.  
  260.  
  261.  
  262. GNU                         1992/07/28                          4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CO(1)                                                       CO(1)
  269.  
  270.  
  271.               For the initial pair, _r_e_v_2 may be omitted.  The
  272.               default is the common ancestor.  If any of the
  273.               arguments indicate branches, the latest revisions
  274.               on those branches are assumed.  The options --ll and
  275.               --uu lock or unlock _r_e_v_1.
  276.  
  277.        --VV     Print s version number.
  278.  
  279.        --VV_n    Emulate RCS version _n_, where _n may be 33, 44, or 55.
  280.               This may be useful when interchanging RCS files
  281.               with others who are running older versions of RCS.
  282.               To see which version of RCS your correspondents are
  283.               running, have them invoke rrlloogg on an RCS file; if
  284.               none of the first few lines of output contain the
  285.               string bbrraanncchh:: it is version 3; if the dates' years
  286.               have just two digits, it is version 4; otherwise,
  287.               it is version 5.  An RCS file generated while
  288.               emulating version 3 will lose its default branch.
  289.               An RCS revision generated while emulating version 4
  290.               or earlier will have a timestamp that is off by up
  291.               to 13 hours.  A revision extracted while emulating
  292.               version 4 or earlier will contain dates of the form
  293.               _y_y//_m_m//_d_d instead of _y_y_y_y//_m_m//_d_d and may also contain
  294.               different white space in the substitution for
  295.               $$LLoogg$$.
  296.  
  297.        --xx_s_u_f_f_i_x_e_s
  298.               Use _s_u_f_f_i_x_e_s to characterize RCS files.  See ccii(1)
  299.               for details.
  300.  
  301. KKEEYYWWOORRDD SSUUBBSSTTIITTUUTTIIOONN
  302.        Strings of the form $$_k_e_y_w_o_r_d$$ and $$_k_e_y_w_o_r_d::_._._.$$ embedded
  303.        in the text are replaced with strings of the form
  304.        $$_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
  305.        below.  Keywords may be embedded in literal strings or
  306.        comments to identify a revision.
  307.  
  308.        Initially, the user enters strings of the form $$_k_e_y_w_o_r_d$$_.
  309.        On checkout, ccoo replaces these strings with strings of the
  310.        form $$_k_e_y_w_o_r_d::_v_a_l_u_e$$_.  If a revision containing strings of
  311.        the latter form is checked back in, the value fields will
  312.        be replaced during the next checkout.  Thus, the keyword
  313.        values are automatically updated on checkout.  This
  314.        automatic substitution can be modified by the --kk options.
  315.  
  316.        Keywords and their corresponding values:
  317.  
  318.        $$AAuutthhoorr$$
  319.               The login name of the user who checked in the
  320.               revision.
  321.  
  322.        $$DDaattee$$ The date and time (UTC) the revision was checked
  323.               in.
  324.  
  325.  
  326.  
  327.  
  328. GNU                         1992/07/28                          5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. CO(1)                                                       CO(1)
  335.  
  336.  
  337.        $$HHeeaaddeerr$$
  338.               A standard header containing the full pathname of
  339.               the RCS file, the revision number, the date (UTC),
  340.               the author, the state, and the locker (if locked).
  341.  
  342.        $$IIdd$$   Same as $$HHeeaaddeerr$$, except that the RCS filename is
  343.               without a path.
  344.  
  345.        $$LLoocckkeerr$$
  346.               The login name of the user who locked the revision
  347.               (empty if not locked).
  348.  
  349.        $$LLoogg$$  The log message supplied during checkin, preceded
  350.               by a header containing the RCS filename, the
  351.               revision number, the author, and the date (UTC).
  352.               Existing log messages are _n_o_t replaced.  Instead,
  353.               the new log message is inserted after $$LLoogg::...$$.
  354.               This is useful for accumulating a complete change
  355.               log in a source file.
  356.  
  357.        $$RRCCSSffiillee$$
  358.               The name of the RCS file without a path.
  359.  
  360.        $$RReevviissiioonn$$
  361.               The revision number assigned to the revision.
  362.  
  363.        $$SSoouurrccee$$
  364.               The full pathname of the RCS file.
  365.  
  366.        $$SSttaattee$$
  367.               The state assigned to the revision with the --ss
  368.               option of rrccss(1) or ccii(1).
  369.  
  370. FFIILLEE MMOODDEESS
  371.        The working file inherits the read and execute permissions
  372.        from the RCS file.  In addition, the owner write
  373.        permission is turned on, unless --kkvv is set or the file is
  374.        checked out unlocked and locking is set to strict (see
  375.        rrccss(1)).
  376.  
  377.        If a file with the name of the working file exists already
  378.        and has write permission, ccoo aborts the checkout, asking
  379.        beforehand if possible.  If the existing working file is
  380.        not writable or --ff is given, the working file is deleted
  381.        without asking.
  382.  
  383. FFIILLEESS
  384.        ccoo accesses files much as ccii(1) does, except that it does
  385.        not need to read the working file.
  386.  
  387. EENNVVIIRROONNMMEENNTT
  388.        RRCCSSIINNIITT
  389.               options prepended to the argument list, separated
  390.               by spaces.  See ccii(1) for details.
  391.  
  392.  
  393.  
  394. GNU                         1992/07/28                          6
  395.  
  396.  
  397.  
  398.  
  399.  
  400. CO(1)                                                       CO(1)
  401.  
  402.  
  403. DDIIAAGGNNOOSSTTIICCSS
  404.        The RCS pathname, the working pathname, and the revision
  405.        number retrieved are written to the diagnostic output.
  406.        The exit status is zero if and only if all operations were
  407.        successful.
  408.  
  409. IIDDEENNTTIIFFIICCAATTIIOONN
  410.        Author: Walter F. Tichy.
  411.        Revision Number: 5.9; Release Date: 1992/07/28.
  412.        Copyright 1982, 1988, 1989 by Walter F. Tichy.
  413.        Copyright 1990, 1991, 1992 by Paul Eggert.
  414.  
  415. SSEEEE AALLSSOO
  416.        ci(1), ctime(3), date(1), ident(1), make(1), rcs(1),
  417.        rcsdiff(1), rcsintro(1), rcsmerge(1), rlog(1), rcsfile(5)
  418.        Walter F. Tichy, RCS--A System for Version Control,
  419.        _S_o_f_t_w_a_r_e_-_-_P_r_a_c_t_i_c_e _& _E_x_p_e_r_i_e_n_c_e 1155, 7 (July 1985),
  420.        637-654.
  421.  
  422. LLIIMMIITTSS
  423.        Links to the RCS and working files are not preserved.
  424.  
  425.        There is no way to selectively suppress the expansion of
  426.        keywords, except by writing them differently.  In nroff
  427.        and troff, this is done by embedding the null-character \\&&
  428.        into the keyword.
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460. GNU                         1992/07/28                          7
  461.  
  462.  
  463.