Basic CVS Tutorial
by David Martin (w/ additions by Sara McMains)

CREATING THE REPOSITORY

The first step is to create a source repository.

	(1) Create a directory to serve as the repository.
	(2) Set the environment variable CVSROOT to the name
	    of the repository directory.
	(3) Execute "cvs init". 

The final step installs some useful CVS bookkeeping stuff.

The environment variable CVSROOT must be set by all clients of the
repository.

(We've already done this. You should add the line

	   setenv CVSROOT /home/cadml/testdir/cvsroot

to your .cshrc file. Make sure that the EDIT environment variable is
set to your favorite editor because CVS will bring it up for you to
add comments every time you commit changes. E.g. add 
	
	setenv EDIT emacs

to your .cshrc file.)

ADDING TO THE REPOSITORY

There are two ways to add stuff to the repository.  Adding a new
directory or a new file to an already checked out module is described
below.  This section shows how to easily bootstrap an entire source
tree into the repository.
		

	(1) cd into the root directory of the source tree
	    to be added.
	(2) Execute "cvs import <dir> <vendortag> <releasetag>".
	    The <dir> directory is a directory name relative to
	    CVSROOT.  This directory CVSROOT/<dir> is created,
	    and everything in PWD is added (recursively) to 
	    CVSROOT/<dir> under CVS control.

The <vendortag> gives a symbolic name to the new version of the entire
source tree.  I don't know what <releasetag> is for, yet it must be
specified....  The man page says:

	You must also specify at least one releasetag to iden-
        tify the files at the leaves created each time you exe-
        cute `cvs import'.

(eg cvs import <dir> cadml r1)

(We set the sticky bit on the CVSROOT directory, so that all the
directories checked in will be cadml group owned and writable. If you
import subdirectories, you may need to manually do a chgrp cadml to
them. Otherwise other group members may have problems with permissions
when they check in files.)


CHECKING OUT MODULES

A module is a collection of stuff in the repository.  Each directory
in the repository is a module.  Modules can be more complex, but that
is not important here.

If you want to work on a module that is in the repository:

	(1) Go to some private directory where you want to
	    work.
	(2) Execute "cvs checkout <module>".  This will
	    create the directory <module> in PWD and in it
	    place a checked-out copy of CVSROOT/<module>.
	(3) Change files at will.  No special CVS commands
	    are needed for simple editing.

(If you want to check out a subdirectory, eg sif/include, & you
already have sif checked out into ~/projects, go to ~/projects and do
cvs checkout sif/include.)

CVS will give you a line for each file "<status> <file>", where status
if one of {U M C A R ?}.  If you are checking out a module for the
first time, status should always be "U".

You can run "cvs checkout" on an already checked-out module to bring
it up-to-date.  This is nearly identical to running "cvs update -d".
However, for basic CVS use, I recommend using "cvs checkout" to create
a local copy of a module, and "cvs update -d" (see below) to
subsequently bring it up-to-date with the repository.


ADDING AND DELETING FILES FROM A CHECKED-OUT MODULE

Once you have checked out a module, you may not only edit files,
but add and delete files as well.  To add a file:

	(1) Create the file in your checked-out module.
	(2) Execute "cvs add <file>".  There can be no "/"s in
	    <file>, so you must be in the same directory.

To delete a file:

	(1) Delete the file from your checked-out module.
	(2) Execute "cvs rm <file>".  "rm", "remove", and "delete"
	    are all synonyms.  There can be no "/"s in <file>, so you
	    must be in the same directory.

Note that simply creating or removing a file is not enough.  You
*must* execute the cvs commands.


UPDATING THE REPOSITORY

Editing, adding, or deleting a file in a checked out module as per the
above directions does not affect the repository in any way.  If you
want to bring the repository up-to-date with your checked-out module,
thereby publishing your changes to the module:

	(1) cd into your check-out module, or a subdirectory
	    thereof.
	(2) Execute "cvs commit".

(This will bring up a file in your default editor, to which you should
add short, meaningful comments about the changes you are checking
in. Then save the file and exit the editor.)

This will merge your changes to PWD and below into the repository.


UPDATING YOUR CHECKED-OUT MODULE

If you want to bring your checked-out module up-to-date with
the repository:

	(1) cd into your check-out module, or a subdirectory
	    thereof.
	(2) Execute "cvs update -d".

This will *merge* anything new in the repository into your local
copy.  Note that if you have made uncommitted changes locally,
they will still exist, and the repository will not see them.

The "-d" option is needed in order to receive directories that
have been added to the repository that don't exist in your local
area.

For each file in the repository and in your local area, CVS
prints a line "<status> <file>", where status is one of:

	U : [Up-to-date]
	    You have not modified your local copy of the file.
	    Changes in the repository were successfully merged
		into your local copy.

	M : [Modified]
	    You have modified your local copy of the file, 
		but have not run "cvs commit".
	    Changes in the repository were successfully merged
		into your local copy.

	C : [Conflict]
	    You have modified your local copy of the file, 
		but have not run "cvs commit".
	    Local changes conflicted with the repository version.
	    Your local copy now contains the merged data.  
	    Your old local copy is in ".#<file>.<version>".

	A : [Added]
	    You have cvs-added this file but have not run "cvs commit".

	R : [Removed]
	    You have cvs-removed this file but have not run "cvs commit".

	? : This file exists in your local area but does not
	    exist in the repository.

The status of a file is presented from the point of view of the
local copy.  Thus, "added" means that it has been added to the 
local area (not that it has been added to the repository).


ADDING AND DELETING DIRECTORIES TO A CHECKED-OUT MODULE

Adding a directory to a checked-out module is just like adding a file:

	(1) Create the directory in your checked-out module.
	(2) Execute "cvs add <dir>".  There can be no "/"s in
	    <dir>, so you must be in the same directory.  

Note that the "cvs add <dir>" command is *not* recursive.  If there
are new files in <dir>, they they must be "cvs add"ed afterwards.

You can delete a directory from a checked-out module, but since there
is no such command "cvs rm <dir>", "cvs commit" does not commit the
deletion.  You can delete all the files from the directory (and commit
those deletions), but the directory will remain in the repository.
This has the annoying side-effect of creating that directory in your
checked-out copy whenever you do a "cvs update -d".  These placeholder
directories are needed in order to check out old versions that use
them.

(If you you use -P as well this should prune those placeholder
directories.) 

DELETING YOUR LOCAL COPY

Since CVS does not lock files on checkout, you can, at any time,
simply delete your local copies of files.  You risk losing any
un-committed changes, however.  To avoid this problem, execute:

	cvs release -d <module>

This will delete your local copy iff you have no un-committed 
changes.


FILE VERSIONS

Normally, each file is assigned a new version only when it is
modified and committed.  It is useful to synchronize all files
at a new version number:

	cvs commit -r2.0

This command will ensure that all files (modified or not) are
assigned a new version.

A similar command that assigned a symbolic tag is:

	cvs tag <label>

This command can be undone with:

	cvs tag -d <label>

A module or file can be checked out according to either numeric
or symbolic tag:

	cvs checkout -r<tag> <module>


STATUS OF FILES

To view the CVS status of your local files:

	cvs status [<files>]

To view the difference between CVS versions:

	cvs diff [-r <version1> [-r <version2>]] <files>

Ommitting both versions gives the diffs between your
local copy and the most recent version in the repository.

Specifying one version gives the diffs between your
local copy and the specified version.

Specifying two versions gives the diffs between those
versions.

To get a detailed history log:

	cvs log


Simple experiment seems to demonstrate that CVS does not
deal with symbolic links at all.  It thinks they are empty
files.


other resources are:

http://www.csc.calpoly.edu/~dbutler/tutorials/winter96/cvs/
http://www.loria.fr/~molli/cvs-index.html


REMOTE CVS, UNIX to UNIX:

This assumes you have the same user name on both machines.

In your .cshrc file, add the two lines
   setenv CVSROOT <host machine>:/<path for CVSROOT>
   setenv CVS_RSH cvs_ssh

		  (e.g. kingkong:/home/cadml/testdir/cvsroot)

Then create the following script and save it as cvs_ssh:

#!/bin/sh
ssh -C $*

(and put it somewhere in your path, chmod it to executable, and rehash
before trying to run it).