Step-by-step instructions to using CVS

Motto: The palest of ink is better than the best memory.
Chinese proverb

Introduction

This page is set up to guide you through using CVS, a tool for file versioning. If you are moderately versed in CVS, you can safely skip this section.

For your project, you'll be starting from a codebase provided by us and you will modify it extensively. Oftentimes, you'll find yourself in the situation of having modified the code in ways that render it unusable (such as during that 3 am coding binge), and you'll want to return to a previous version of your code, which you know it is stable. So you want to "turn the clock back".

Also, when two students are working on the same project, you'll want to be able to make changes to files concurrently and be able to merge changes into a single codebase. Things can get rapidly out of control when using improvised tools (email, "Are you changing file X? Oops..." and so on).

On top of that, we (instructor and TA) might occasionally fix the elusive last bug in the codebase, and you'll need to merge those bug fixes with your own code that already contains your additions and changes. That might sound like magic, but it turns out there are simple line-oriented algorithms that can do a great job at merging similar text from various sources. A robust tool implementing such algorithms is CVS, which stands for Concurrent Versions System.

Working with CVS for CSE401

Here are the steps you need to take.

Make sure you have access to a Unix command prompt. You can obtain a Unix-like environment on Windows machines by downloading and installing Cygwin.
Execute a remote shell into one of the instructional machines (e.g. attu, amlia, kiska, or umnak—see also more information on available resources) by typing:
```
% ssh your_cse_username@instructional_server
```
Execute the following command to start a shell with proper credentials for your group:
```
% chgrpsh +cse401x
```
x is a placeholder for a letter that will be assigned to by your TA. Students doing joint work will share the same letter. It looks like nothing has happened, but in reality you are now a member of the group cse401x for the remainder of the session. You can check that by typing:
```
% groups
```
You should see cse401x among your groups.
Make sure you can run cvs, for now just by typing:
```
% cvs
```
at the command prompt (%). You ought to see a help message.
Next, you'll need to create your own repository so you can reap the benefits of CVS. The repository is a directory that you should see as private to CVS. Manipulate that directory through CVS only.
You create a repository by executing the init CVS command, like this:
```
% cvs -d /projects/instr/qtr/cse401/x init
```
(where qtr is the code for the current quarter, e.g. 04au or 05sp)
Now create a local directory that you will do your work in. Let's call it myproj. It should be in your home directory. In that directory, get the CVS administrative files like this:
```
% mkdir myproj
% cd myproj
% cvs -d /projects/instr/qtr/cse401/x co .
```
This command will leave you with the directories CVSROOT and CVS.

Edit the file myproj/CVSROOT/cvswrappers and add the following lines to it:

*.class -k 'b'
*.gif -k 'b'
*.png -k 'b'
*.pdf -k 'b'
*.gz -k 'b'
*.jar -k 'b'

Commit the thusly-modified file back to the repository. From your myproj directory, issue:
```
% cvs commit -m "Updated cvswrappers"
```
Note that in this case you don't need to specify the repository via the -d option. This is because cvs has planted its helper directories and looks up the repository name in a file called ./CVS/Root.
As of now, your repository is ready for prime time.
Now, you'll need to get the fresh code into your repository for the first time. To do that, create a temporary directory (let's call it temp), change to that directory, copy there the zip file that we distribute, and issue the following cvs import command.
```
% cd temp
% unzip MiniJava.zip
% cvs -d /projects/instr/qtr/cse401/x import -m "Initial release" . CSE401 MiniJava_1_0
```
After importing, remove the temp directory.
Now, you have everything up and you may want to start doing some actual work. Go back to working directory for your project, myproj, and get everything in CVS by incanting:
```
% cvs checkout .
```
You should get pretty much the same files that were in the zip file.
Whenever you are pleased with the quality of your code, you may want to check it in the repository:
```
% cd myproj
% cvs commit -m "Added cool feature"
```
As said, on occasions we may distribute new, updated zip files, which you want to merge into your codebase. Again, create a fresh empty directory dir-holding-the-zip-file, copy the zip file that we distribute to it, and issue another import command:
```
% cd dir-holding-the-zip-file
% unzip the-zip-file.zip
% cvs -d /projects/instr/qtr/cse401/x import -m "Version 2" . CSE401 MiniJava_2_0
```
Note that you are issuing essentially the exact same command, but this time with a new version tag (and a new comment, which you can use later to identify versions). Again, after importing, remove the temporary dir-holding-the-zip-file.
Now your CVS repository contains your own work and our patches, nicely merged.
Whenever you want to refresh your local copy (directory myproj) with the contents of the CVS repository, e.g. after importing patches from us, you issue a cvs update command:
```
% cd myproj
% cvs update
```
Again, no need to specify the root directory because CVS looks it up in CVS/Root that the checkout command had created.
On occasion, you will need to add new files to your repository.
If you're adding new ASCII files, say "coolfeature.java", then you need to issue:
```
% cvs add coolfeature.java
```
If you're adding new binary files, you need to use the -kb when adding:
```
% cvs add -kb coolicon.gif
```
The next time you do a cvs commit, your new files will be added to the repository.

That's about it! If you have any problem, specify the step at which you got stuck when asking your TA for help. Good luck!

chambers at cs andrei at cs