home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / dev / RevisionControl / HWGRCS / hwgrcs / man / ci.man < prev    next >
Text File  |  1993-01-19  |  21KB  |  595 lines
  1.  
  2.  
  3.  
  4. CI(1)                    USER COMMANDS                      CI(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      ci - check in RCS revisions
  10.  
  11. SYNOPSIS
  12.      ci [_o_p_t_i_o_n_s] _f_i_l_e ...
  13.  
  14. DESCRIPTION
  15.      ci stores new  revisions  into  RCS  files.   Each  pathname
  16.      matching an RCS suffix is taken to be an RCS file.  All oth-
  17.      ers are assumed to be working  files  containing  new  revi-
  18.      sions.   ci  deposits the contents of each working file into
  19.      the corresponding RCS file.   If  only  a  working  file  is
  20.      given, ci tries to find the corresponding RCS file in an RCS
  21.      subdirectory and then in the working file's directory.   For
  22.      more details, see FILE NAMING below.
  23.  
  24.      For ci to work, the caller's login must  be  on  the  access
  25.      list,  except  if  the access list is empty or the caller is
  26.      the superuser or the owner of the file.   To  append  a  new
  27.      revision  to  an  existing  branch, the tip revision on that
  28.      branch must be locked by the caller.  Otherwise, only a  new
  29.      branch can be created.  This restriction is not enforced for
  30.      the owner of the file if non-strict  locking  is  used  (see
  31.      rcs(1)).  A lock held by someone else may be broken with the
  32.      rcs command.
  33.  
  34.      Unless the -f option is given, ci checks whether  the  revi-
  35.      sion  to  be  deposited  differs from the preceding one.  If
  36.      not, instead of creating a new revision ci  reverts  to  the
  37.      preceding  one.   To revert, ordinary ci removes the working
  38.      file and any lock; ci -l keeps and ci -u removes  any  lock,
  39.      and  then  they  both generate a new working file much as if
  40.      co -l or co -u had been applied to the  preceding  revision.
  41.      When reverting, any -n and -s options apply to the preceding
  42.      revision.
  43.  
  44.      For each revision deposited, ci prompts for a  log  message.
  45.      The log message should summarize the change and must be ter-
  46.      minated by end-of-file or by a line containing . by  itself.
  47.      If several files are checked in ci asks whether to reuse the
  48.      previous log message.  If the standard input is not a termi-
  49.      nal,  ci suppresses the prompt and uses the same log message
  50.      for all files.  See also -m.
  51.  
  52.      If the RCS file does not exist, ci creates it  and  deposits
  53.      the  contents  of  the  working file as the initial revision
  54.      (default number: 1.1).  The access list  is  initialized  to
  55.      empty.   Instead of the log message, ci requests descriptive
  56.      text (see -t below).
  57.  
  58.      The number _r_e_v of the deposited revision can be given by any
  59.      of  the  options -f, -I, -k, -l, -M, -q, -r, or -u.  _r_e_v may
  60.  
  61.  
  62.  
  63. GNU                  Last change: 1991/10/07                    1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CI(1)                    USER COMMANDS                      CI(1)
  71.  
  72.  
  73.  
  74.      be symbolic, numeric, or mixed.  If _r_e_v is $, ci  determines
  75.      the revision number from keyword values in the working file.
  76.  
  77.      If _r_e_v is a revision number, it  must  be  higher  than  the
  78.      latest one on the branch to which _r_e_v belongs, or must start
  79.      a new branch.
  80.  
  81.      If _r_e_v is a branch rather than a revision  number,  the  new
  82.      revision  is  appended  to that branch.  The level number is
  83.      obtained by incrementing the tip  revision  number  of  that
  84.      branch.  If _r_e_v indicates a non-existing branch, that branch
  85.      is created with the initial revision numbered _r_e_v.1.
  86.  
  87.      If _r_e_v is omitted, ci  tries  to  derive  the  new  revision
  88.      number  from  the  caller's  last  lock.   If the caller has
  89.      locked the tip revision of a branch,  the  new  revision  is
  90.      appended  to  that  branch.   The  new  revision  number  is
  91.      obtained by incrementing the tip revision  number.   If  the
  92.      caller locked a non-tip revision, a new branch is started at
  93.      that revision by incrementing the highest branch  number  at
  94.      that revision.  The default initial branch and level numbers
  95.      are 1.
  96.  
  97.      If _r_e_v is omitted and the caller has no lock, but  owns  the
  98.      file  and locking is not set to _s_t_r_i_c_t, then the revision is
  99.      appended to the default branch (normally the trunk; see  the
  100.      -b option of rcs(1)).
  101.  
  102.      Exception: On the trunk, revisions can be  appended  to  the
  103.      end, but not inserted.
  104.  
  105. OPTIONS
  106.      -r[_r_e_v]
  107.           checks in a revision, releases the corresponding  lock,
  108.           and removes the working file.  This is the default.
  109.  
  110.           The -r option has an unusual meaning in ci.   In  other
  111.           RCS  commands,  -r  merely specifies a revision number,
  112.           but in ci it also releases a lock and removes the work-
  113.           ing file.  See -u for a tricky example.
  114.  
  115.      -l[_r_e_v]
  116.           works like -r, except it performs an  additional  co -l
  117.           for  the deposited revision.  Thus, the deposited revi-
  118.           sion is immediately checked out again and locked.  This
  119.           is  useful  for saving a revision although one wants to
  120.           continue editing it after the checkin.
  121.  
  122.      -u[_r_e_v]
  123.           works like -l, except that the  deposited  revision  is
  124.           not  locked.   This  lets  one  read  the  working file
  125.           immediately after checkin.
  126.  
  127.  
  128.  
  129. GNU                  Last change: 1991/10/07                    2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CI(1)                    USER COMMANDS                      CI(1)
  137.  
  138.  
  139.  
  140.           The -l, -r, and -u options are mutually  exclusive  and
  141.           silently override each other.  For example, ci -u -r is
  142.           equivalent to ci -r because -r overrides -u.
  143.  
  144.      -f[_r_e_v]
  145.           forces a deposit; the new revision is deposited even it
  146.           is not different from the preceding one.
  147.  
  148.      -k[_r_e_v]
  149.           searches the working file for keyword values to  deter-
  150.           mine  its  revision  number,  creation date, state, and
  151.           author (see co(1)), and assigns  these  values  to  the
  152.           deposited revision, rather than computing them locally.
  153.           It also generates a default login  message  noting  the
  154.           login  of the caller and the actual checkin date.  This
  155.           option is useful for software distribution.  A revision
  156.           that is sent to several sites should be checked in with
  157.           the -k option at these sites to preserve  the  original
  158.           number, date, author, and state.  The extracted keyword
  159.           values and the default log message  may  be  overridden
  160.           with  the  options  -d, -m, -s, -w, and any option that
  161.           carries a revision number.
  162.  
  163.      -q[_r_e_v]
  164.           quiet mode; diagnostic output is not printed.  A  revi-
  165.           sion  that  is  not different from the preceding one is
  166.           not deposited, unless -f is given.
  167.  
  168.      -I[_r_e_v]
  169.           interactive mode; the user is prompted  and  questioned
  170.           even if the standard input is not a terminal.
  171.  
  172.      -d[_d_a_t_e]
  173.           uses _d_a_t_e for the checkin date and time.  The  _d_a_t_e  is
  174.           specified  in  free format as explained in co(1).  This
  175.           is useful for lying about the checkin date, and for  -k
  176.           if no date is available.  If _d_a_t_e is empty, the working
  177.           file's time of last modification is used.
  178.  
  179.      -M[_r_e_v]
  180.           Set the modification time on any new working file to be
  181.           the  date  of  the  retrieved  revision.   For example,
  182.           ci -d -M -u _f does not  alter  _f's  modification  time,
  183.           even  if  _f's  contents change due to keyword substitu-
  184.           tion.  Use  this  option  with  care;  it  can  confuse
  185.           make(1).
  186.  
  187.      -m_m_s_g
  188.           uses the string _m_s_g as the log message  for  all  revi-
  189.           sions checked in.
  190.  
  191.      -n_n_a_m_e
  192.  
  193.  
  194.  
  195. GNU                  Last change: 1991/10/07                    3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CI(1)                    USER COMMANDS                      CI(1)
  203.  
  204.  
  205.  
  206.           assigns the symbolic name _n_a_m_e to  the  number  of  the
  207.           checked-in  revision.   ci  prints  an error message if
  208.           _n_a_m_e is already assigned to another number.
  209.  
  210.      -N_n_a_m_e
  211.           same as -n, except that it overrides a previous assign-
  212.           ment of _n_a_m_e.
  213.  
  214.      -s_s_t_a_t_e
  215.           sets the state of the checked-in revision to the  iden-
  216.           tifier _s_t_a_t_e.  The default state is Exp.
  217.  
  218.      -t_f_i_l_e
  219.           writes descriptive text from the contents of the  named
  220.           _f_i_l_e  into  the  RCS  file, deleting the existing text.
  221.           The _f_i_l_e may not begin with -.
  222.  
  223.      -t-_s_t_r_i_n_g
  224.           Write descriptive text from the  _s_t_r_i_n_g  into  the  RCS
  225.           file, deleting the existing text.
  226.  
  227.           The -t option, in both its forms, has effect only  dur-
  228.           ing  an  initial checkin; it is silently ignored other-
  229.           wise.
  230.  
  231.           During the initial checkin, if  -t  is  not  given,  ci
  232.           obtains  the  text  from  standard input, terminated by
  233.           end-of-file or by a line containing . by  itself.   The
  234.           user  is prompted for the text if interaction is possi-
  235.           ble; see -I.
  236.  
  237.           For backward compatibility with older versions of  RCS,
  238.           a bare -t option is ignored.
  239.  
  240.      -w_l_o_g_i_n
  241.           uses _l_o_g_i_n for the author field of the deposited  revi-
  242.           sion.  Useful for lying about the author, and for -k if
  243.           no author is available.
  244.  
  245.      -V_n  Emulate RCS version _n.  See co(1) for details.
  246.  
  247.      -x_s_u_f_f_i_x_e_s
  248.           specifies the suffixes for RCS files.  A nonempty  suf-
  249.           fix  matches  any  pathname  ending  in the suffix.  An
  250.           empty suffix matches any pathname of the form  RCS/_f_i_l_e
  251.           or  _p_a_t_h/RCS/_f_i_l_e.  The -x option can specify a list of
  252.           suffixes separated by /.  For example, -x,v/  specifies
  253.           two  suffixes: ,v and the empty suffix.  If two or more
  254.           suffixes are specified, they are tried  in  order  when
  255.           looking  for  an  RCS file; the first one that works is
  256.           used for that file.  If no RCS file is found but an RCS
  257.           file can be created, the suffixes are tried in order to
  258.  
  259.  
  260.  
  261. GNU                  Last change: 1991/10/07                    4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CI(1)                    USER COMMANDS                      CI(1)
  269.  
  270.  
  271.  
  272.           determine the new RCS file's  name.   The  default  for
  273.           _s_u_f_f_i_x_e_s  is installation-dependent; normally it is ,v/
  274.           for hosts like Unix that permit commas in  file  names,
  275.           and  is  empty  (i.e.  just the empty suffix) for other
  276.           hosts.
  277.  
  278. FILE NAMING
  279.      Pairs of RCS files and working files  may  be  specified  in
  280.      three ways (see also the example section).
  281.  
  282.      1) Both the RCS file and the working file  are  given.   The
  283.      RCS  pathname is of the form _p_a_t_h_1/_w_o_r_k_f_i_l_e_X and the working
  284.      pathname is of the  form  _p_a_t_h_2/_w_o_r_k_f_i_l_e  where  _p_a_t_h_1/  and
  285.      _p_a_t_h_2/  are (possibly different or empty) paths, _w_o_r_k_f_i_l_e is
  286.      a filename, and _X is an RCS suffix.  If _X is  empty,  _p_a_t_h_1/
  287.      must be RCS/ or must end in /RCS/.
  288.  
  289.      2) Only the RCS file is given.  Then  the  working  file  is
  290.      created  in  the  current  directory and its name is derived
  291.      from the name of the RCS file by  removing  _p_a_t_h_1/  and  the
  292.      suffix _X.
  293.  
  294.      3) Only the working file is given.  Then ci  considers  each
  295.      RCS  suffix  _X  in turn, looking for an RCS file of the form
  296.      _p_a_t_h_2/RCS/_w_o_r_k_f_i_l_e_X or (if the former is not found and _X  is
  297.      nonempty) _p_a_t_h_2/_w_o_r_k_f_i_l_e_X.
  298.  
  299.      If the RCS file is specified without a path in 1) and 2), ci
  300.      looks for the RCS file first in the directory ./RCS and then
  301.      in the current directory.
  302.  
  303.      ci reports an error if an attempt to open an RCS file  fails
  304.      for  an  unusual  reason, even if the RCS file's pathname is
  305.      just one of several possibilities.  For example, to suppress
  306.      use  of RCS commands in a directory _d, create a regular file
  307.      named _d/RCS so that casual attempts to use RCS commands in _d
  308.      fail because _d/RCS is not a directory.
  309.  
  310. EXAMPLES
  311.      Suppose ,v is an RCS suffix and the current  directory  con-
  312.      tains a subdirectory RCS with an RCS file io.c,v.  Then each
  313.      of the following commands check  in  a  copy  of  io.c  into
  314.      RCS/io.c,v as the latest revision, removing io.c.
  315.  
  316.           ci  io.c;    ci  RCS/io.c,v;   ci  io.c,v;
  317.           ci  io.c  RCS/io.c,v;    ci  io.c  io.c,v;
  318.           ci  RCS/io.c,v  io.c;    ci  io.c,v  io.c;
  319.  
  320.      Suppose instead that the empty suffix is an RCS  suffix  and
  321.      the  current  directory  contains a subdirectory RCS with an
  322.      RCS file io.c.  The each of the following commands checks in
  323.      a new revision.
  324.  
  325.  
  326.  
  327. GNU                  Last change: 1991/10/07                    5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. CI(1)                    USER COMMANDS                      CI(1)
  335.  
  336.  
  337.  
  338.           ci  io.c;    ci  RCS/io.c;
  339.           ci  io.c  RCS/io.c;
  340.           ci  RCS/io.c  io.c;
  341.  
  342. FILE MODES
  343.      An RCS file created by ci inherits the read and execute per-
  344.      missions  from  the  working  file.   If the RCS file exists
  345.      already, ci preserves its read and execute permissions.   ci
  346.      always turns off all write permissions of RCS files.
  347.  
  348. FILES
  349.      Several temporary files may be created in the directory con-
  350.      taining  the  working file, and also in the temporary direc-
  351.      tory (see TMPDIR under ENVIRONMENT).  A  semaphore  file  or
  352.      files  are created in the directory containing the RCS file.
  353.      With a nonempty suffix, the semaphore names begin  with  the
  354.      first  character of the suffix; therefore, do not specify an
  355.      suffix whose first character could  be  that  of  a  working
  356.      filename.   With  an  empty  suffix, the semaphore names end
  357.      with _ so working filenames should not end in _.
  358.  
  359.      ci never changes an  RCS  or  working  file.   Normally,  ci
  360.      unlinks  the  file  and  creates  a  new one; but instead of
  361.      breaking a chain of one or more symbolic  links  to  an  RCS
  362.      file,  it  unlinks the destination file instead.  Therefore,
  363.      ci breaks any hard or symbolic links to any working file  it
  364.      changes;  and  hard  links to RCS files are ineffective, but
  365.      symbolic links to RCS files are preserved.
  366.  
  367.      The effective user must be able  to  search  and  write  the
  368.      directory  containing the RCS file.  Normally, the real user
  369.      must be able to read the RCS and working files and to search
  370.      and  write  the  directory containing the working file; how-
  371.      ever, some older hosts cannot easily switch between real and
  372.      effective  users,  so  on  these hosts the effective user is
  373.      used for all accesses.  The effective user is  the  same  as
  374.      the  real  user  unless your copies of ci and co have setuid
  375.      privileges.   As  described  in  the  next  section,   these
  376.      privileges  yield  extra security if the effective user owns
  377.      all RCS files and directories, and  if  only  the  effective
  378.      user can write RCS directories.
  379.  
  380.      Users can control access to RCS files by setting the permis-
  381.      sions of the directory containing the files; only users with
  382.      write access to the directory can use RCS commands to change
  383.      its  RCS  files.  For example, in hosts that allow a user to
  384.      belong to several groups, one can make a group's RCS  direc-
  385.      tories  writable to that group only.  This approach suffices
  386.      for informal projects, but it means that  any  group  member
  387.      can  arbitrarily  change the group's RCS files, and can even
  388.      remove them entirely.  Hence more formal projects  sometimes
  389.      distinguish between an RCS administrator, who can change the
  390.  
  391.  
  392.  
  393. GNU                  Last change: 1991/10/07                    6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. CI(1)                    USER COMMANDS                      CI(1)
  401.  
  402.  
  403.  
  404.      RCS files at will, and other project members, who can  check
  405.      in new revisions but cannot otherwise change the RCS files.
  406.  
  407. SETUID USE
  408.      To prevent anybody but their RCS administrator from deleting
  409.      revisions,  a  set  of users can employ setuid privileges as
  410.      follows.
  411.  
  412.      o+ Check that the host supports RCS setuid  use.   Consult  a
  413.        trustworthy expert if there are any doubts.  It is best if
  414.        the seteuid() system call  works  as  described  in  Posix
  415.        1003.1a  Draft  5,  because  RCS can switch back and forth
  416.        easily between real and effective users, even if the  real
  417.        user  is root.  If not, the second best is if the setuid()
  418.        system call supports saved setuid (the  {_POSIX_SAVED_IDS}
  419.        behavior  of  Posix  1003.1-1990);  this fails only if the
  420.        real user is root.  If RCS detects any failure in  setuid,
  421.        it quits immediately.
  422.  
  423.      o+ Choose a user _A to serve as RCS administrator for the  set
  424.        of  users.   Only _A will be able to invoke the rcs command
  425.        on the users' RCS files.  _A should  not  be  root  or  any
  426.        other  user with special powers.  Mutually suspicious sets
  427.        of users should use different administrators.
  428.  
  429.      o+ Choose a path name _B that will be a directory of files  to
  430.        be executed by the users.
  431.  
  432.      o+ Have _A set up _B to contain copies of ci and  co  that  are
  433.        setuid  to  _A  by copying the commands from their standard
  434.        installation directory _D as follows:
  435.  
  436.           mkdir  _B
  437.           cp  _D/c[io]  _B
  438.           chmod  go-w,u+s  _B/c[io]
  439.  
  440.      o+ Have each user prepend _B to their path as follows:
  441.  
  442.           PATH=_B:$PATH;  export  PATH  # ordinary shell
  443.           set  path=(_B  $path)  # C shell
  444.  
  445.      o+ Have _A create each RCS directory _R with write access  only
  446.        to _A as follows:
  447.  
  448.           mkdir  _R
  449.           chmod  go-w  _R
  450.  
  451.      o+ If you want to let only certain users read the RCS  files,
  452.        put  the  users into a group _G, and have _A further protect
  453.        the RCS directory as follows:
  454.  
  455.  
  456.  
  457.  
  458.  
  459. GNU                  Last change: 1991/10/07                    7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. CI(1)                    USER COMMANDS                      CI(1)
  467.  
  468.  
  469.  
  470.           chgrp  _G  _R
  471.           chmod  g-w,o-rwx  _R
  472.  
  473.      o+ Have _A copy old RCS files (if any) into _R, to ensure  that
  474.        _A owns them.
  475.  
  476.      o+ An RCS file's access list limits who can check in and lock
  477.        revisions.  The default access list is empty, which grants
  478.        checkin access to anyone who can read the  RCS  file.   If
  479.        you want limit checkin access, have _A invoke rcs -a on the
  480.        file; see rcs(1).  In particular, rcs -e -a_A limits access
  481.        to just _A.
  482.  
  483.      o+ Have _A initialize any new RCS  files  with  rcs -i  before
  484.        initial checkin, adding the -a option if you want to limit
  485.        checkin access.
  486.  
  487.      o+ Give setuid privileges only to ci, co,  and  rcsclean;  do
  488.        not give them to rcs or to any other command.
  489.  
  490.      o+ Do not use other setuid commands to invoke  RCS  commands;
  491.        setuid is trickier than you think!
  492.  
  493. ENVIRONMENT
  494.      RCSINIT
  495.           options prepended to the argument  list,  separated  by
  496.           spaces.   A  backslash escapes spaces within an option.
  497.           The RCSINIT options are prepended to the argument lists
  498.           of  most  RCS commands.  Useful RCSINIT options include
  499.           -q, -V, and -x.
  500.  
  501.      TMPDIR
  502.           Name of the  temporary  directory.   If  not  set,  the
  503.           environment   variables  TMP  and  TEMP  are  inspected
  504.           instead and the first value found is taken; if none  of
  505.           them  are  set, a host-dependent default is used, typi-
  506.           cally /tmp.
  507.  
  508. DIAGNOSTICS
  509.      For each revision, ci prints the RCS file, the working file,
  510.      and the number of both the deposited and the preceding revi-
  511.      sion.  The exit status is zero if and only if all operations
  512.      were successful.
  513.  
  514. IDENTIFICATION
  515.      Author: Walter F. Tichy.
  516.      Revision Number: 5.9; Release Date: 1991/10/07.
  517.      Copyright c 1982, 1988, 1989 by Walter F. Tichy.
  518.      Copyright c 1990, 1991 by Paul Eggert.
  519.  
  520. SEE ALSO
  521.      co(1), ident(1), make(1), rcs(1),  rcsclean(1),  rcsdiff(1),
  522.  
  523.  
  524.  
  525. GNU                  Last change: 1991/10/07                    8
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. CI(1)                    USER COMMANDS                      CI(1)
  533.  
  534.  
  535.  
  536.      rcsintro(1), rcsmerge(1), rlog(1), rcsfile(5)
  537.      Walter  F.  Tichy,  RCS--A  System  for   Version   Control,
  538.      _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 15, 7 (July 1985), 637-654.
  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. GNU                  Last change: 1991/10/07                    9
  592.  
  593.  
  594.  
  595.