A Brief Introduction to CVS

CS230/330 - Operating Systems (Winter, 2002).

Overview

CVS is version control system that is particularly useful when working on large software projects or when working in groups. In a nutshell, CVS stores your software in a special repository that holds all of the versions of your software as well as information about when files were modified, who modified them, and logs describing why changes were made. Some of the more notable features of CVS include the ability to "undo" changes if you mess up and making life easier when multiple people are working on a single project.

All of the gory details about CVS can be found at www.cvshome.org. This document describes the bare essentials that you need to know for this class.

The Repository

Your account on the class machines should already be properly configured to use CVS. In your home directory, there should be a directory called CVS. This directory is the repository that will hold all of your files. Under normal circumstances, you should never have to look in this directory. Likewise, you should never modify any files found in this directory.

Creating a new CVS project

To create a new CVS project, first create a directory with all of your working files. For example, you might have a directory "myproject" that looks like this:

% cd myproject
% ls
Makefile
README
bar.c
foo.c
%

Make sure your directory is clean and only contains the files you want to place in the repository. Object files, executables, core files, and editor backup files should be deleted from the directory in this process.

Now, import your directory into the CVS repository as follows:

% cd myproject
% cvs import myproject yourname start
N myproject/Makefile
N myproject/README
N myproject/bar.c
N myproject/foo.c

No conflicts created by this import
%

After typing the 'cvs import' command, an editor will appear asking you to type in a log message. This message should simply be a short description of the project. After saving the message, the files will be imported into the repository.

Note : To save the log message and exit from emacs, you will have to type Control-X Control-S followed by Control-X Control-C. To save the message and exit from vi, you should type ":w" followed by ":q".

After importing a directory into CVS, you should either rename or remove the original project directory and checkout a fresh version from the repository.

Checking out a project

To check a project out of the CVS repository use the 'cvs checkout' command like this:

% cvs checkout myproject
cvs checkout: Updating myproject
U myproject/Makefile
U myproject/README
U myproject/bar.c
U myproject/foo.c

Now, all of your original files should be restored in a new directory "myproject".

Making changes

When working in a CVS project directory, you can modify all of the files exactly as you normally would. However, after you are satisfied with a set of changes, it is a good idea to commit those changes back to the repository. This can be done for individual files or for an entire directory using the 'cvs commit' command like this:

% cvs commit foo.c
Checking in foo.c;
/u1/dave/CVSROOT/myproject/foo.c,v  <--  foo.c
new revision: 1.2; previous revision: 1.1
done
%

Before committing the file, an editor will be started where you will be asked to enter a log message describing your changes. As a shortcut, you can also enter a change message on the command line like this:

% cvs commit -m "Fixed the segmentation fault error" foo.c

Changes made to an entire directory can be committed in the same manner. For example:

% cvs commit -m "Handin" myproject

Adding new files and directories

When you add new files and directories to your project, they are not automatically added to the CVS repository. Instead, you must explicitly add the files using the 'cvs add' command like this:

% cvs add spam.c
cvs add: scheduling file `spam.c' for addition
cvs add: use 'cvs commit' to add this file permanently

This only tells CVS that a new file will be added. The addition does not take effect until you commit changes using the 'cvs commit' command.

Removing files from the repository

To remove a file from the repository, use the 'cvs remove' command. For example:

% rm foo.c
% cvs remove foo.c
cvs remove: scheduling `foo.c' for removal
cvs remove: use 'cvs commit' to remove this file permanently

Again, this command only takes effect after you have committed your changes with the 'cvs commit' command.

Tagging a project

When your code is in a reasonably stable state, you can use the 'cvs tag' command to apply a name to your current project state. For example:

% cvs tag version1 myproject

Later on, if you ever need to go back to "version1", you can go into a clean directory and type "cvs checkout -r version1". This will check out the version of code that was tagged as "version1". This can be particularly useful if you proceed to mess something up beyond repair---you can simply restore the last tagged version and restart.

Doing a time-warp

If you are really in a bind and need to go back to a previous version of code, you can specify a date with the 'cvs checkout' command. For example:

% cvs checkout -D "2 days ago" myproject

Of course, this will only work if you have been diligent about committing files to your CVS repository. Do a 'man cvs' for all of the various date specification options.

Handing in a Project

All projects in this course will be handed in via CVS. Prior to handin, you need to go through the following checklist:

Make sure your code compiles and runs.
Make sure all of the necessary files have been added to the repository. Use the 'cvs add' command to do this.
Commit all of your changes on the top-level project directory using 'cvs commit myproject'.
Tag the project with an easy to remember name such as "handin".
Test your handin by checking it out to a new directory and building everything. For example:
```
% mkdir Junk
% cd Junk
% cvs checkout myproject
... list of files ...
% cd myproject
% make
... compiler junk ...
% run it
```
If you are missing any files, this last step will fail. Go back to the original project directory and add the required files.

General tips

When making lots of program changes, CVS can be a lifesaver. As you work on the kernel project, you are encouraged to check in files as frequently as you see fit. There is no penalty for checking in several hundred versions of the same file (all we care about is the most recent version). CVS can be used by multiple people, each working on a version of a project in their own directory. When working with multiple people, it is always a good idea to do a 'cvs update' before committing any changes. This will bring your code up to date with any changes that someone else might have committed while you were working.

Where to go from here?

More information about CVS is available at www.cvshome.org. More details about each of the commands can be found by typing 'man cvs'.