====== Brief Intro to CVS ======

===== Checking out code =====

To check out a module:

  cvs -d REPOSITORY checkout MODULENAME

REPOSITORY is the path to the CVS Repository (at BIAC this is CVSRepo under the Source share).  MODULENAME is the name of the module that you want to check out.  This will create a new //working directory// MODULENAME that has the latest revisions of all files checked in for this module.

===== Updating your working directory =====

To update your working directory with the latest revisions, change to that directory and run:

  cvs update -d -P

The -d option will create new directories that have been added since the last time you updated, and -P will "prune" directories that have been deleted or emptied.

===== Adding a file to a module =====

To add a file to the repository, make sure it is in a working directory that you checked out of CVS, and do:

  cvs add -m "MESSAGE" FILENAME

You may wish to add CVS revision/name fields to your file.  You can do this by putting $Id$ anywhere in a comment.  You can look at nearly any file in the BIAC MATLAB tools or the "xmlheader" module for examples of that.  You can also put $Log$ in a comment and any messages you provide when committing changes will appear there too magically.  Generally this is good to have at the end of the file.

===== Committing changes =====

To commit changes you make to files in your working directory:

  cvs commit -m "MESSAGE" FILENAME

If someone else made changes to that same file, it might ask you to update first.  The update may "merge" updates into your copy and if there are conflicting changes, it will tell you that and the file will contain blocks where the old and new code is.  You'll need to merge the conflicts manually.

FILENAME in all cases can be a directory, and can be eliminated in the commit case if you just want to commit everything that has changed in the current directory.

===== Tagging =====

At some point, if you are going to release or deploy a version of your code, it's a good idea to "tag" it with a release name or number so you can check it out by name later if needed.  If you have everything with the right versions in your working directory:

  cvs tag RELEASENAME

While revision numbers are specific to each file, tags can be applied to the whole project.

===== Specifying revisions =====

You can restrict yourself or affect only particular revisions with the -r option, like:

  cvs update -r 1.56 FILENAME

will grab revision 1.56 of the file.  "HEAD" is a special revision always indicating the latest revision on the trunk.

  cvs update -r RELEASENAME

will grab the revisions of everything in the current directory corresponding to the tag RELEASENAME.

Note that if you specify -r, that revision or tag name will become "sticky" and so further updates or diffs will always stop at the revision or tag specified by the -r option.  Sometimes this is not what you want.  To reset to the default HEAD revision, use the -A option:

  cvs update -A

===== Showing differences =====

Another useful command is:

  cvs diff

which will show you the differences between the current working directory and the 

===== More info =====

CVS tutorials on the web are better than the CVS man page, which is only good for reference.