home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / rcs / rcsintro.man < prev    next >
Text File  |  1992-02-19  |  10KB  |  237 lines
  1. NAME
  2.      rcsintro - introduction to RCS commands
  3.  
  4. DESCRIPTION
  5.      The Revision Control System (RCS) manages multiple revisions
  6.      of files.  RCS automates the storing, retrieval, logging,
  7.      identification, and merging of revisions.  RCS is useful for
  8.      text that is revised frequently, for example programs,
  9.      documentation, graphics, papers, and form letters.
  10.  
  11.      The basic user interface is extremely simple.  The novice
  12.      only needs to learn two commands: ci(1) and co(1).  ci,
  13.      short for "check in", deposits the contents of a file into
  14.      an archival file called an RCS file.  An RCS file contains
  15.      all revisions of a particular file.  co, short for "check
  16.      out", retrieves revisions from an RCS file.
  17.  
  18.   Functions of RCS
  19.      +    Store and retrieve multiple revisions of text.  RCS
  20.           saves all old revisions in a space efficient way.
  21.           Changes no longer destroy the original, because the
  22.           previous revisions remain accessible.  Revisions can be
  23.           retrieved according to ranges of revision numbers,
  24.           symbolic names, dates, authors, and states.
  25.  
  26.      +    Maintain a complete history of changes.  RCS logs all
  27.           changes automatically.  Besides the text of each
  28.           revision, RCS stores the author, the date and time of
  29.           check-in, and a log message summarizing the change.
  30.           The logging makes it easy to find out what happened to
  31.           a module, without having to compare source listings or
  32.           having to track down colleagues.
  33.  
  34.      +    Resolve access conflicts.  When two or more programmers
  35.           wish to modify the same revision, RCS alerts the
  36.           programmers and prevents one modification from
  37.           corrupting the other.
  38.  
  39.      +    Maintain a tree of revisions.  RCS can maintain
  40.           separate lines of development for each module.  It
  41.           stores a tree structure that represents the ancestral
  42.           relationships among revisions.
  43.  
  44.      +    Merge revisions and resolve conflicts.  Two separate
  45.           lines of development of a module can be coalesced by
  46.           merging.  If the revisions to be merged affect the same
  47.           sections of code, RCS alerts the user about the
  48.           overlapping changes.
  49.  
  50.      +    Control releases and configurations.  Revisions can be
  51.           assigned symbolic names and marked as released, stable,
  52.           experimental, etc.  With these facilities,
  53.           configurations of modules can be described simply and
  54.           directly.
  55.  
  56.      +    Automatically identify each revision with name,
  57.           revision number, creation time, author, etc.  The
  58.           identification is like a stamp that can be embedded at
  59.           an appropriate place in the text of a revision.  The
  60.           identification makes it simple to determine which
  61.           revisions of which modules make up a given
  62.           configuration.
  63.  
  64.      +    Minimize secondary storage.  RCS needs little extra
  65.           space for the revisions (only the differences).  If
  66.           intermediate revisions are deleted, the corresponding
  67.           deltas are compressed accordingly.
  68.  
  69.   Getting Started with RCS
  70.      Suppose you have a file f.c that you wish to put under
  71.      control of RCS.  If you have not already done so, make an
  72.      RCS directory with the command
  73.  
  74.           mkdir  RCS
  75.  
  76.      Then invoke the check-in command
  77.  
  78.           ci  f.c
  79.  
  80.      This command creates an RCS file in the RCS directory,
  81.      stores f.c into it as revision 1.1, and deletes f.c.  It
  82.      also asks you for a description.  The description should be
  83.      a synopsis of the contents of the file.  All later check-in
  84.      commands will ask you for a log entry, which should
  85.      summarize the changes that you made.
  86.  
  87.      Files in the RCS directory are called RCS files; the others
  88.      are called working files.  To get back the working file f.c
  89.      in the previous example, use the check-out command
  90.  
  91.           co  f.c
  92.  
  93.      This command extracts the latest revision from the RCS file
  94.      and writes it into f.c.  If you want to edit f.c, you must
  95.      lock it as you check it out with the command
  96.  
  97.           co  -l  f.c
  98.  
  99.      You can now edit f.c.
  100.  
  101.      Suppose after some editing you want to know what changes
  102.      that you have made.  The command
  103.  
  104.           rcsdiff  f.c
  105.  
  106.      tells you the difference between the most recently checked-
  107.      in version and the working file.  You can check the file
  108.      back in by invoking
  109.  
  110.           ci  f.c
  111.  
  112.      This increments the revision number properly.
  113.  
  114.      If ci complains with the message
  115.  
  116.           ci error: no lock set by your name
  117.  
  118.      then you have tried to check in a file even though you did
  119.      not lock it when you checked it out.  Of course, it is too
  120.      late now to do the check-out with locking, because another
  121.      check-out would overwrite your modifications.  Instead,
  122.      invoke
  123.  
  124.           rcs  -l  f.c
  125.  
  126.      This command will lock the latest revision for you, unless
  127.      somebody else got ahead of you already.  In this case,
  128.      you'll have to negotiate with that person.
  129.  
  130.      Locking assures that you, and only you, can check in the
  131.      next update, and avoids nasty problems if several people
  132.      work on the same file.  Even if a revision is locked, it can
  133.      still be checked out for reading, compiling, etc.  All that
  134.      locking prevents is a check-in by anybody but the locker.
  135.  
  136.      If your RCS file is private, i.e., if you are the only
  137.      person who is going to deposit revisions into it, strict
  138.      locking is not needed and you can turn it off.  If strict
  139.      locking is turned off, the owner of the RCS file need not
  140.      have a lock for check-in; all others still do.  Turning
  141.      strict locking off and on is done with the commands
  142.  
  143.           rcs  -U  f.c     and     rcs  -L  f.c
  144.  
  145.      If you don't want to clutter your working directory with RCS
  146.      files, create a subdirectory called RCS in your working
  147.      directory, and move all your RCS files there.  RCS commands
  148.      will look first into that directory to find needed files.
  149.      All the commands discussed above will still work, without
  150.      any modification.  (Actually, pairs of RCS and working files
  151.      can be specified in three ways: (a) both are given, (b) only
  152.      the working file is given, (c) only the RCS file is given.
  153.      Both RCS and working files may have arbitrary path prefixes;
  154.      RCS commands pair them up intelligently.)
  155.  
  156.      To avoid the deletion of the working file during check-in
  157.      (in case you want to continue editing or compiling), invoke
  158.  
  159.           ci  -l  f.c     or     ci  -u  f.c
  160.  
  161.      These commands check in f.c as usual, but perform an
  162.      implicit check-out.  The first form also locks the checked
  163.      in revision, the second one doesn't.  Thus, these options
  164.      save you one check-out operation.  The first form is useful
  165.      if you want to continue editing, the second one if you just
  166.      want to read the file.  Both update the identification
  167.      markers in your working file (see below).
  168.  
  169.      You can give ci the number you want assigned to a checked in
  170.      revision.  Assume all your revisions were numbered 1.1, 1.2,
  171.      1.3, etc., and you would like to start release 2.  The
  172.      command
  173.  
  174.           ci  -r2  f.c     or     ci  -r2.1  f.c
  175.  
  176.      assigns the number 2.1 to the new revision.  From then on,
  177.      ci will number the subsequent revisions with 2.2, 2.3, etc.
  178.      The corresponding co commands
  179.  
  180.           co  -r2  f.c     and     co  -r2.1  f.c
  181.  
  182.      retrieve the latest revision numbered 2.x and the revision
  183.      2.1, respectively.  co without a revision number selects the
  184.      latest revision on the trunk, i.e. the highest revision with
  185.      a number consisting of two fields.  Numbers with more than
  186.      two fields are needed for branches.  For example, to start a
  187.      branch at revision 1.3, invoke
  188.  
  189.           ci  -r1.3.1  f.c
  190.  
  191.      This command starts a branch numbered 1 at revision 1.3, and
  192.      assigns the number 1.3.1.1 to the new revision.  For more
  193.      information about branches, see rcsfile(5).
  194.  
  195.   Automatic Identification
  196.      RCS can put special strings for identification into your
  197.      source and object code.  To obtain such identification,
  198.      place the marker
  199.  
  200.           $Id$
  201.  
  202.      into your text, for instance inside a comment.  RCS will
  203.      replace this marker with a string of the form
  204.  
  205.           $Id:  filename  revision  date  time  author  state  $
  206.  
  207.      With such a marker on the first page of each module, you can
  208.      always see with which revision you are working.  RCS keeps
  209.      the markers up to date automatically.  To propagate the
  210.      markers into your object code, simply put them into literal
  211.      character strings.  In C, this is done as follows:
  212.  
  213.           static char rcsid[] = "$Id$";
  214.  
  215.      The command ident extracts such markers from any file, even
  216.      object code and dumps.  Thus, ident lets you find out which
  217.      revisions of which modules were used in a given program.
  218.  
  219.      You may also find it useful to put the marker $Log$ into
  220.      your text, inside a comment.  This marker accumulates the
  221.      log messages that are requested during check-in.  Thus, you
  222.      can maintain the complete history of your file directly
  223.      inside it.  There are several additional identification
  224.      markers; see co(1) for details.
  225.  
  226. IDENTIFICATION
  227.      Author: Walter F. Tichy.
  228.      Revision Number: 5.2; Release Date: 1992/02/17.
  229.      Copyright 1982, 1988, 1989 by Walter F. Tichy.
  230.      Copyright 1990, 1991, 1992 by Paul Eggert.
  231.  
  232. SEE ALSO
  233.      ci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsintro(1),
  234.      rcsmerge(1), rlog(1)
  235.      Walter F. Tichy, RCS--A System for Version Control,
  236.      Software--Practice & Experience 15, 7 (July 1985), 637-654.
  237.