CS 341 Software Design	Course Overview Instructor Course Schedule Project Policies and Grading Useful Links Questions

Using CVS

CVS is a version control system available on Unix. Each file that you use in each assignment, including diagrams, documentation and source code, should be managed with CVS so that you can back out of changes if you like.

Items that are managed by CVS are stored in CVS repositories. A CVS repository contains a collection of files each of which is stored in a format that allows any previous version of that file to be extracted. It does this by maintaining a listing of the first version of your document in its entirety. Each time that you update the CVS file, it determines what has changed and adds a list of the changes to the file. In this way, multiple versions of a file are stored much more compactly than if each version was stored in its entirety.

Initializing CVS

Before using CVS, you must create a repository and configure your environment to know where that repository is.

Creating a CVS Repository

You should create a CVS repository. For me to create a repository, I would enter the following from a Unix prompt:

   -> cvs -d /home/blerner/cvs init

Note that you must provide an absolute pathname for the location of the repository.

Identifying your CVS Repository

To use CVS, you need to tell it where the CVS repository exists that you are using. You should add a line to your .local_bashrc file similar to the following:

   export CVSROOT=/home/blerner/cvs

You should also tell cvs what editor you like to use:

   export CVSEDITOR=/usr/local/bin/emacs

Start a new shell to get cvs properly initialized.

Creating a CVS Project

A repository may contain multiple projects. The next thing you will want to do is create a CVS project for your 341 assignments. To create a project, you "import" the files that make up the initial version of the project. First, set up a directory structure that you will use for 341. For example, you might simply create a cs341 directory and then add a subdirectory for each assignment as you work on them. While it's easy to add directories, it's rather difficult to move, rename, or delete directories that cvs controls. So think carefully about how you organize your directories as you create them.

Next, you use the cvs import command identifying the project name to use within cvs and two string "tags". The values of the tags are not particularly important for this project, but they are required. Be sure that you are inside the directory that you think of as your top-level project directory when you issue the import command. Here is how you would do this:

-> cd cs341/
-> cvs import cs341 cs341 fall06

When you issue this command, cvs will bring up a text editor. You should provide a log entry identifying what it is you are importing. It will create a directory in your cvs repository called cs341. It will then copy everything from your current directory and subdirectories into this repository.

Getting files into your project

Before modifying anything that has been imported into a project, you need to check out a copy of the project. Do not work directly on the files that you import!. In fact, after importing the project, it may be a good idea to delete the directories you imported so that you don't confuse yourself. Of course, if the directories were not empty, don't delete the directory until after you do the checkout below and can convince yourself everything is there!

At this point you have an empty project. What you do next is to "checkout" the project:

-> cvs checkout cs341

This will create a directory in your current directory called cs341. It will have one subdirectory called CVS which contains files cvs cares about but that you should not modify.

When you start working on an assignment, you should create your files within this checked-out repository. For example, you might create a directory "hw1" within "cs341" and then create one or more files to hold your solution within the "hw1" directory. To get cvs to version these files, you need to get these files into the repository. To do that, you must first "add" the files:

  -> cvs add hw1
  -> cd hw1
  -> cvs add Solution.java   (or whatever your solution file is called)

The add command only tells cvs that these files should be considered part of the project. It doesn't actually copy them to the repository. To get them into the repository, use the "commit" command:

  -> cvs commit

This will copy all new and modified files from your current directory and its added subdirectories into the cvs repository. An editor will start that will prompt you for a log message about what has changed. If the file is modified, rather than new, it will save the file in a way that allows you to compare it with previous versions or to check out an older version if you like.

Removing a File from a CVS Project

If the repository contains a file that you want to delete, you delete the file from your local directory and use the cvs remove command to tell CVS to also remove it from the repository:

  -> rm myfile
  -> cvs remove myfile

Substitute the name of the file for "myfile". You may enter a list of file names in one remove command.

CVS will report that it is "scheduling `myfile' for removal". The files are not actually removed from the cvs repository until you commit your changes.

Saving a Modified File in the Repository

To save the current version of your files in the repository, you "commit" your changes:

  -> cvs commit 

CVS will find all the files in your current directory that you added with the "add" command, removed with the "remove" command, and all the files that you modified. It will open up an editor indicating which files are being committed and ask you to make a log entry. You should describe the nature of the change you are making. This will create a new version in your repository. You should never modify the contents of any CVS file or repository directly. Instead, you should use CVS commands exclusively to checkout and commit changes.

It is a good idea for you to commit changes whenever you get a new feature working. That way, if the changes do not work out, you will be able to back out of those changes by reverting to an earlier version of your file that the repository has remembered for you.

Finding out What has Changed

If you want to find out what has changed in your directory since your last commit, use the cvs status command. For each file, this will report the status of the file, version numbers, and dates associated with the files. The status is somewhat different than what is reported with the update command:

Up-to-date

The version in the repository is the same as the copy in your directory.

 

Locally added

The file was created by you using the cvs add command. There is currently no version of the file in the repository.

 

Locally removed

The file was removed by you using the cvs remove command. The file still exists in the repository.

 

Locally modified

The file was modified in your directory.

 

Needs patch

The file was modified in the repository. (This will only happen if you have checked out the file in more than one place or if multiple people are working together on a project, sharing a cvs repository.)

You can also use the cvs diff command to find out what has changed between the version of a file in your directory and the most recent version in the repository. It's very useful to do this prior to a commit so that you can provide a meaningful log message if you forget exactly what you have done.

General rule of thumb

You should never commit changes that are not internally consistent. Once things are internally consistent, you should do a commit. If you're working heavily on an assignment, you may do a few commits in one day.

Getting More Help

You can get more help about CVS by reading the online manual.