CVS Quick Start Guide for CS162

Dominic Antonelli, cs162-ta@imail.eecs.berkeley.edu

Last updated 12 September 2005

Group IDs and Members

Each project group has a CVS group ID associated with it. This group ID is of the form cs162-gN where N is a number representing your group (no leading 0s). You can find out your group ID by looking up your user ID in this list of users.

In order to use CVS, you should login to your cs162 instructional account. Be sure that your login shell is either csh or tcsh; this should be the case by default, but if you have changed your shell (say, by running chsh), you need to change it back. This is very important.

When you login, it will generate an SSH key and ask you for a passphrase. Please allow this process to finish, and enter a passphare that you will remember. This is necessary for us to set up your group account.

Some time after you do this process, we will have the cvs group accounts created (we'll post a note on the announcements page and the newsgroup). Once that is done, you can continue by running the command

  cvsgroup cs162-gNNN

where cs162-gNNN is your group ID, as explained above. This command will ask for your SSH passphrase. Do not forget your SSH passphrase. You will need all your group members present as this command will ask for each of your passphrases.

Once this command has been issued you can use CVS commands. All commands will automatically refer to your group's CVS repository, which is accessible only through this mechanism. The repositories are located on a different disk from your class directories. This means that you will not have to sacrifice any disk space.

You should not need to set CVSROOT or any other environment variable to use CVS; after running the 'cvsgroup' command everything is set up for you. It probably makes sense to run cvsgroup from your .login script so it's executed every time you login.

Setting up a repository

One group member (ONLY!) should import the Nachos code into the repository. To do this, cd into the Nachos source directory. Make sure you go into the Nachos directory!. Then do:
```
  cvs init
  cvs import nachos groupid start
```
to import the Nachos files into your CVS repository. Be sure to run these commands from the 'nachos' directory! Otherwise you will recursively import everything in the current directory into CVS, which is probably not what you want.
Since you just imported this code into the repository, you want to get rid of the original nachos directory, and work on the version you will check out in the next step. So, move the directory nachos out of the way:
```
  mv nachos nachos.old
```
Only one member of each group should use these commands; all other members will skip this step and continue on.

Basic CVS Usage

First, check out a local copy of the Nachos code:
```
  cvs co nachos
```
This will create a nachos directory with all of the Nachos code in it. ALL group members need to do this, even if you already have a copy of the nachos code. If you do have a copy of the nachos code already, delete it or move it out of the way. If you do not check out the copy from the repository, you will not be able to commit, update, etc.
Edit your local copy of the files.
When you are ready to make your changes available to other members of your group, commit the changes back to the repository:
```
  cvs commit
```
This will start up an editor for you to enter a log entry describing your changes. It makes a lot of sense enter a descriptive entry of the changes you made -- this will make tracking changes a lot easier.
Note that you cannot commit changes unless your local files are up to date: that is, that you have been editing the most recent copy. See the next step for details.
For other users to see the changes, they need to do:
```
  cvs update -d
```
which will update their local files to be in sync with the repository.
If there are conflicts (that is, someone else edited the same file while you were in the process of editing it), you will be notified at this point and given a chance to fix the conflict. You will not be able to do a commit until you resolve the conflict. In order to fix a conflict, you edit the conflicting file, which will contain new lines with both the old and new versions. Decide which version you want to keep (or merge them somehow).
cvs update and cvs commit list all the files they touch preceded by a one-character code signifying the change. Here is a quick key to the code:
- M The file is modified in your working directory.
- U The file was brought up to date with respect to the repository.
- P The file was patched to bring it up to date with respect to the repository.
- ? The file is in your working directory, but not in the repository.
- C A conflict was detected while trying to merge your changes to file with changes from the source repository. Edit the file, by hand to fix up the changes. Look for the string "<<<<"
- A The file is scheduled to be added to the source repository at the next commit point.
- R The file is scheduled to be removed from the source repository at the next commit point.
To add a file or directory to the repository, just do:
```
  cvs add filenames...
```
After cvs add you need to cvs commit for the addition to take effect.
To remove a file, first remove it from your local copy:
```
  rm filename
```
Then remove it from the CVS repository:
```
  cvs remove filename
  cvs commit
```

Other CVS Features

You can check out copy of code as it looked at a given time:

  cvs co -D "yesterday" nachos
  cvs co -D "1/26/01 8:00" nachos

You can tag a version of the file or tree for later use. This allows you to check out (or otherwise refer to) that particular version of the tree later on. For example, if you have a good, working version of the code and want to tag it as such, you can do:

  cvs tag working1

Later, you can check out the exact version of that code:

  cvs co -r working1 nachos

You can also look at a 'diff' of changes from one version of the code to another:

  cvs diff -D "yesterday"
  cvs diff -r 1.3 foo.java

Also, the cvs log command will show you the log entries for each version of files in the tree, so you can eyeball the changes that were made over time.

Type man cvs to get a lot more information on using this wonderful tool.

Important Caveats!

Note that CVS does not allow you to rename files - you need to "remove" the file and then "add" the file under the new name. In general it's best not to rename files, since this loses all of the editing history for that file.

Also note that CVS does not allow you to remove or rename directories once they have been added to the repository. THIS IS VERY IMPORTANT!! Do not add directories to the repository temporarily - you can never get rid of them. This is a real drawback to CVS, but it's something you just have to live with.

Generally it is best to only check in source files to the repository -- anything that can be generated (say, a Java .class file) should not be checked in, since it's redundant (and confusing if the generated .class files don't match up with the source files).