What is CVS?

CVS is a software tool that a group can use to allow members to work on a single document concurrently. It can also be used to maintain multiple (past) versions of a text file in a way that allows you to revert to past versions and to view the evolution of document. As a side benefit, it also serves as an efficient backup mechanism for your project's files.

Who should use CVS?

If you are working on a project that involves multiple revisions of a flat text file (ASCII), then you should consider using CVS. Types of projects that lend themselves to using CVS are software projects and the writing of papers or presentations in LaTeX. When such projects involve several writers working on the same set of documents, then CVS's value increases.

How to use CVS.

CVS is available for most OS platforms, so anyone with a computer can set up a CVS system for their own files on whatever computer they own. But the Mathematical Biology program offers program participants the service of the Mathematical Biology server: pyrite. This server can host a CVS service. What follows are instructions for getting CVS service to support your work in the program.

Terminology

Module

A collection of one or more files that constitute a project or a coherent part of a project. Choose a module name that has meaning such as "tickProject".

Repository

A collection of one or more modules that make up the entire team's work. Authentication is at the repository level, so everyone working on any aspect of a project shares a repository. Often a repository has only one module.

Set up a project repository.

To use CVS served from pyrite, you must first have a repository created. This repository must be named, so choose a name and email it to Jason Miller (millerj (at) truman.edu), along with the Truman network usernames of the people who will need to access it. Once this is created, you can create one or more modules in the repository.

Take note that creation of the repository will also involve the creation of a password that you will use to access the repository. (The username for access will be your Truman network username, if you have one.)

Login to your repository

Once the repository is created by the administrator, you need to log in to the server. You should only need to do this once. Execute the following command at your command line:

cvs -d ":pserver:[username]@pyrite.truman.edu:/usr/local/cvsrep/[repositoryname]" login

and use the password that the administrator gave you when the repository was created.

Populate your repository

You've probably already created files that will go into the repository. Put them in some convenient folder/directory called [dirname], change your working directory to [dirname], and think up a good module name. Execute the following command (on a single line):

cvs -d ":pserver:[username]@pyrite.truman.edu:/usr/local/cvsrep/[repositoryname]" import [modulename] [username] start

This will create the module and put your files into it.

Checkout/Commit/Update your Module

You are now ready to check out your files from the repository. Make sure your working directory has changed from the directory that contains your original copies of your files (that were imported). Only this way will you immediately see the stunning power of CVS.

With your working directory some place innocuous, execute the following command at the command prompt:

cvs -d ":pserver:[username]@pyrite.truman.edu:/usr/local/cvsrep/[repositoryname]" checkout [module]

This should create a folder/directory called [module] in your working directory, and in that folder/directory you will find the files that you had imported into the module in the above step.

Just for fun, check out another copy of your module in another location on your local computer. We'll use this in a moment.

Next, back in your original copy of the module, modify one of your files in some way. Add some lines of text, delete some characters of text, or reorganize rows of text. Save the modified files and then execute the following command at the command prompt:

cvs -d ":pserver:[username]@pyrite.truman.edu:/usr/local/cvsrep/[repositoryname]" commit

This will commit the contents of the module as they exist on your local machine. That is, this will "copy" your local files back to pyrite in a way that is cognizant of the changes you have made. The new version will also get its own number for whatever tracking purposes you have.

Now go to the original copy of the module. This one should have copies of the files that do not have the changes you made an committed. Execute the following command at the command prompt:

cvs -d ":pserver:[username]@pyrite.truman.edu:/usr/local/cvsrep/[repositoryname]" udpate

This will update the files in the working directory to reflect the changes you made and committed to the module earlier!

Imagine this happening with multiple people working on a common set of files: the commit/update cycle helps everyone communicate the changes they make almost in real time!

Is there More CVS Goodness?

With CVS you can also recover previous states of your document (i.e., undo changes you've made) and create "branched" versions of your document. There's more you can do, of course; see the Cederquist manual for CVS for details.

CVS will also help you if, while you and a colleague were working on a shared document, you both revised the same section of text. When the second of you commits their changes, CVS alerts you to a 'conflict' and asks you to resolve the conflict by choosing the correct revision from those made. This makes CVS a 'trusting' versioning system. You and your colleagues should agree on how to resolve such conflicts if they occur.

Other questions about CVS?

If you're in Truman's summer research program, and if you are a member of this Mathematical Biology portal, you can ask questions by posting them as comments on this mini-HOWTO (below).