4. CVS Mini-Howto

CVS (Concurrent Version-control System) is a free software package
available from the GNU archive nearest you.  You'll need version 1.8.1
or later to work with the Amanda repository.  CVS in turn requires
RCS, and you'll probably want the GNU diff/diff3 from the textutils
package too.  These all install easily on most Unix platforms.

CVS can seem to be a complicated package from its documentation, but
most of the complexity has to do with managing repositories, or
dealing with the intricacies of branches and tags, things that a CVS
user doesn't normally have to bother with.

The basic model of CVS is that a master copy of the sources, called th
"repository" is kept on a server machine.  Each developer can "checkout"
a copy of the sources to do their work on.  Multiple developers can work
on the same file at the same time.  Developers "commit" their changes
back to the repository when ready.  Once a developer has committed a
change to a file that you are also working on, CVS will not let you
commit your changes until you first "update" your working directory to
be in sync with the version in the repository.  The update process
merges your changes with those made to the repository since your
checkout.  Conflicts are flagged for you to look at and resolve by hand.

The important CVS commands are (from the man page):

       cvs checkout modules...
              A  necessary preliminary for most cvs work: creates
              your private copy of the source for modules  (named
              collections of source; you can also use a path rel-
              ative to the source repository here).  You can work
              with  this  copy  without  interfering with others'
              work.  At least one subdirectory  level  is  always
              created.

       cvs update
              Execute  this  command  from  within  your  private
              source directory  when  you  wish  to  update  your
              copies  of  source  files  from  changes that other
              developers have made to the source in  the  reposi-
              tory.

       cvs add file...
              Use this command to enroll new files in cvs records
              to  the  repository  the  next  time  you  run `cvs
              commit'.  Note: You should  use  the  `cvs  import'
              command  to  bootstrap  new sources into the source
              repository.  `cvs add' is only used for  new  files
              to an already checked-out module.

       cvs remove file...
              Use  this  command (after erasing any files listed)
              to declare that you wish to  eliminate  files  from
              the repository.  The removal does not affect others
              until you run `cvs commit'.

       cvs commit file...
              Use this command when you wish to ``publish''  your
              changes  to other developers, by incorporating them
              in the source repository.

       cvs diff 
              Show differences between files in working directory
              and source repository, or between two revisions  in
              source repository.  (Does not change either reposi-
              tory or working directory.)

Some additional notes:

a. Before you can execute any CVS commands, you need to set your CVSROOT
   environment variable as follows (I put it in my .cshrc):
        $ setenv CVSROOT amcore@cvs.amanda.org:/homes/amcore/cvsroot

   You also need to use ssh, which means you should set CVS_RSH to be ssh:
        $ setenv CVS_RSH ssh

b. The "-n" option ("do not execute anything that will change the disk")
   is very useful for seeing what a command will do without damaging
   anything.  For example, it's often good to periodically run:
        $ cvs -n update
   to see what you've changed, and what's changed in the repository.

c. You'll often see, when updating and committing, lists of files with
   single letters before them - this is CVS telling you the disposition
   of each file.  These codes are in the CVS man page, buried on page
   twenty-something in the description of the update command.  I include
   those codes here for more easy reference:

     U  The file was brought up to date with respect to the repository.
        This is done for any file that exists in the repository but not
        in your source, and for files that you haven't changed but are
        not the most recent versions available in the repository.

     A  The file has been added to your private copy of the sources, and
        will be added to the RCS source repository when you run `cvs
        commit' on the file.  This is a reminder to you that the file
        needs to be committed.

     R  The file has been removed from your private copy of the sources,
        and will be removed from the RCS source repository when you run
        `cvs commit' on the file.  This is a reminder to you that the
        file needs to be committed.

     M  The file is modified in your working  directory.  `M' can
        indicate one of two states for a file you're working on: either
        there were no modifications to the same file in the repository,
        so that your file remains as you last saw it; or there were
        modifications in the repository as well as in your copy, but
        they were merged successfully, without conflict, in your
        working directory.

     C  A conflict was detected while trying to merge your changes to
        the file with changes from the source repository.  The file (the
        copy in your working directory) is now the output of the
        rcsmerge(1) command on the two versions; an unmodified copy of
        your file is also in your working directory, with the name
        `.#file.version', where version is the RCS revision that your
        modified file started from.  (Note that some systems
        automatically purge files that begin with `.#' if they have not
        been accessed for a few days.  If you intend to keep a copy of
        your original file, it is a very good idea to rename it.)

     ?  The file is in your working directory, but does not correspond
        to anything in the source repository, and is not in the list of
        files for cvs to ignore (see the description of the -I option).
