home *** CD-ROM | disk | FTP | other *** search
/ PC World 1999 August / PCWorld_1999-08_cd.bin / doc / HOWTO / mini / RCS < prev    next >
Text File  |  1998-05-08  |  9KB  |  265 lines
  1.   The RCS MINI-HOWTO
  2.   Robert Kiesling
  3.   v1.4, 14 August 1997
  4.  
  5.   This document covers basic installation and usage of RCS, the GNU
  6.   Revision Control System, under Linux.  It also covers the installation
  7.   of the diff(1) and diff3(1) utilities, which are necessary for RCS to
  8.   operate.  This document may be reproduced freely, in whole or in part,
  9.   provided that any usage of this document conforms to the general copy¡
  10.   right notice of the HOWTO series of the Linux Documentation Project.
  11.   See the file COPYRIGHT for details.  Send all complaints, suggestions,
  12.   errata, and any miscellany to kiesling@terracom.net, so I can keep
  13.   this document as complete and up to date as possible.
  14.   ______________________________________________________________________
  15.  
  16.   Table of Contents
  17.  
  18.  
  19.   1. Overview of RCS.
  20.  
  21.   2. System requirements.
  22.  
  23.   3. Compiling RCS from Source.
  24.  
  25.   4. Creating and maintaining archives.
  26.  
  27.   5. (TT
  28.  
  29.   6. Revision histories.
  30.  
  31.   7. Including RCS data in working files.
  32.  
  33.   8. RCS and
  34.  
  35.  
  36.  
  37.   ______________________________________________________________________
  38.  
  39.   1.  Overview of RCS.
  40.  
  41.   RCS, the revision control system, is a suite of programs that tracks
  42.   changes in text files and controls shared access to files in work
  43.   group situations.  It is generally used to maintain source code
  44.   modules.  It lends itself to tracking revisions of document files as
  45.   well.
  46.  
  47.   RCS was written by Walter F. Tichy and Paul Eggert.  The latest
  48.   version which has been ported to Linux is RCS Version 5.7.  There is
  49.   also a semi-official, threaded version available.  Much of the
  50.   information in this HOWTO is taken from the RCS man pages.
  51.  
  52.   RCS includes the rcs(1) program, which controls RCS archive file
  53.   attributes, ci(1) and co(1), which check files in and out of RCS
  54.   archives, ident(1), which searches RCS archives by keyword
  55.   identifiers, rcsclean(1), a program to clean up files that are not
  56.   being worked on or haven't changed, rcsdiff(1), which runs diff(1) to
  57.   compare the revisions, rcsmerge(1), which merges two RCS branches into
  58.   a single working file, and rlog(1), which prints RCS log messages.
  59.  
  60.   Files archived by RCS may be text of any format, or binary if the diff
  61.   program used to generate change files handles 8-bit data.  Files may
  62.   optionally include identification strings to aid in tracking by
  63.   ident(1).  RCS uses the utilities diff(1) and diff3(3) to generate the
  64.   change files between revisions.  A RCS archive consists of the initial
  65.   revision of a file, which is version 1.1, and a series of change
  66.   files, one for each revision.  Each time a file is checked out of an
  67.   archive with co(1), edited, and checked back into the archive with
  68.   ci(1), the version number is increased, for example, to 1.2, 1.3, 1.4,
  69.   and so on for successive revisions.
  70.  
  71.   The archives themselves commonly reside in a ./RCS subdirectory,
  72.   although RCS has other options for archive storage.
  73.  
  74.   For an overview of RCS, see the rcsintro(1) manual page.
  75.  
  76.  
  77.  
  78.   2.  System requirements.
  79.  
  80.   RCS needs diff(1) and diff3(3) to generate the context diff files
  81.   between revisions.  The diff utilities suite needs to be installed on
  82.   your system, and when you install RCS, the software will check for its
  83.   presence.
  84.  
  85.   Precompiled diffutils binaries are available at:
  86.  
  87.   ftp://sunsite.unc.edu/pub/Linux/utils/text/diffutils-2.6.bin.ELF.tar.gz
  88.  
  89.  
  90.   and its mirror sites.  If you need to compile diff(1), et al., from
  91.   source, it is located at:
  92.  
  93.   ftp://prep.ai.mit.edu/pub/gnu/diffutils-2.7.tar.gz
  94.  
  95.  
  96.   and its mirror sites.
  97.  
  98.   You will also need to have the ELF libraries installed on your system
  99.   if you want to install pre-built binaries.  See the ELF-HOWTO for
  100.   further details.
  101.  
  102.  
  103.  
  104.   3.  Compiling RCS from Source.
  105.  
  106.   Get the source distribution of RCS Version 5.7.  It is available at
  107.  
  108.   ftp://sunsite.unc.edu/pub/Linux/devel/vc/rcs-5.7.src.tar.gz
  109.  
  110.  
  111.   and its mirrors. After you have unpacked the archive into your source
  112.   tree, you need to configure RCS for your system.  This is done via the
  113.   configure script in the source directory, which you need to execute
  114.   first.  This will generate a Makefile and the appropriate conf.sh for
  115.   your system.  You can then type
  116.  
  117.   make install
  118.  
  119.  
  120.   which will build the binaries.  At some point you may need to su to
  121.   root so the binaries can be installed in the correct directories.
  122.  
  123.  
  124.  
  125.   4.  Creating and maintaining archives.
  126.  
  127.   The program rcs(1) does the work or creating archives and modifying
  128.   their attributes.  A summary of rcs(1) options may be found in the
  129.   rcs(1) manual page.
  130.  
  131.   The easiest way to create an archive is first to mkdir RCS in the
  132.   current directory, then initialize the archive with the
  133.   rcs -i name_of_work_file
  134.  
  135.  
  136.   command.  This creates and archive with the name
  137.   ./RCS/name_of_work_file,v and requests a text message describing the
  138.   archive, but it does not deposit any revisions in the archive.  You
  139.   can turn on or off strict archive locking with the commands
  140.  
  141.   rcs -L name_of_work_file
  142.  
  143.  
  144.   and
  145.  
  146.   rcs -U name_of_work_file
  147.  
  148.  
  149.   respectively.  There are other options for controlling access to the
  150.   archive, setting its format, and setting revision numbers, which are
  151.   covered in the rcs(1) manual page.
  152.  
  153.  
  154.  
  155.   5.  ci(1)  and co(1) .
  156.  
  157.   ci(1) and co(1) are the commands used to check files in and out of
  158.   their RCS archives.  The ci(1) command may also be used to a check a
  159.   file both in and out of an archive.  In their simplest forms, ci(1)
  160.   and co(1) take only the name of the working file.
  161.  
  162.   ci name_of_work_file
  163.  
  164.  
  165.   and
  166.  
  167.   co name_of_work_file
  168.  
  169.  
  170.   The command form
  171.  
  172.   ci -l name_of_work_file
  173.  
  174.  
  175.   checks in the file with locking enabled, and
  176.  
  177.   co -l name_of_work_file
  178.  
  179.  
  180.   is performed automatically. That is, ci -l checks the file out again
  181.   with locking enabled.
  182.  
  183.   ci -u name_of_work_file
  184.  
  185.  
  186.   checks the file into the archive, and checks it out again with locking
  187.   disabled.  In all cases, the user is prompted for a log message.
  188.  
  189.   ci(1) will also create a RCS archive if one does not exist already.
  190.  
  191.   If you don't specify a revision, ci(1) increments the version number
  192.   of the last revision locked in the archive, and appends the revised
  193.   working file to it.  If you specify a revision on an existing branch,
  194.   it must be higher than the existing revision numbers.  ci(1) will also
  195.   create a new branch if you specify the revision of a branch which does
  196.   not exist.  See the ci(1) and co(1) man pages for details.
  197.  
  198.  
  199.   ci(1) and co(1) have various options for interactive and non-
  200.   interactive use.  Again, see the ci(1) and co(1) man pages for
  201.   details.
  202.  
  203.  
  204.   6.  Revision histories.
  205.  
  206.   The rlog(1) program provides information about the archive file and
  207.   the logs of each revision stored in it.  A command like
  208.  
  209.   rlog work_file_name
  210.  
  211.  
  212.   will print the version history of the file, each revision's creation
  213.   date and userids of author and the person who locked the file.  You
  214.   can specify archive attributes and revision parameters to view.
  215.  
  216.  
  217.  
  218.   7.  Including RCS data in working files.
  219.  
  220.   co(1) maintains a list of keywords of the RCS database which are
  221.   expanded when the working file is checked out.  The keyword $Id$ in a
  222.   document will expand to a string which contains the file name,
  223.   revision number, the date checked out, the author, the revision
  224.   status, and the locker, if any.  Including the keyword $Log$ will
  225.   expand to the document's revision history log.
  226.  
  227.   These and other keywords may be used as search criteria of the RCS
  228.   archive.  See the ident(1) man page for further details.
  229.  
  230.  
  231.   8.  RCS and emacs(1)  Version Control.
  232.  
  233.   The Version Control facility of emacs(1) works as a front end to RCS.
  234.   This information applies specifically to Version 19.34 of GNU Emacs,
  235.   which is provided with the major Linux distributions.  When editing a
  236.   file with emacs(1) which is registered with RCS, the command vc-
  237.   toggle-read-only (bound to C-x C-q by default) will check a file in to
  238.   the emacs's Version Control, and then into RCS.  Emacs will open a
  239.   buffer where you can type a log message to be included in the RCS log.
  240.   When you are finished typing a log entry, type C-c C-c to terminate
  241.   your input and proceed with the check-in process.
  242.  
  243.   If you have selected strict locking for the file with RCS, you must
  244.   re-lock the file for editing by emacs(1).  You can check the file out
  245.   for emacs's Version Control with the command % in buffer-menu mode.
  246.  
  247.   For more information, see the GNU Emacs Manual and the Emacs info
  248.   pages.
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.