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