LMU Computer Science undergraduates are strongly encouraged, and in many cases required, to maintain a relatively complete electronic portfolio of all coursework in a revsion control system, such as CVS. Maintaining an electronic portfolio of your work has several important benefits:

• You can more easily compose application letters for jobs and graduate schools that require a listing of notable projects completed during school.
• The process of turning in certain assignments is simplified, since many professors may prefer to just extract homework from your electronic repository.
• Some professors may wish to make corrections or give feedback by writing directly to your repository.
• You gain all the advantages of revision control:
  • free backups,
  • access from any computer with an Internet connection,
  • ease of working on collaborative projects,
  • the ability to branch, merge, and, especially, revert.
• You learn how to manage projects by breaking them up into logical phases (milestones)
• You gain valuable industry preparation: revision control systems are routinely used in nearly every business.

These notes cover only about 3% of everything you can do with CVS, but at least it is a useful 3%.

Every LMU Computer Science student gets a account which contains, among many other things, a public-facing website, a private database, and a private CVS repository. When you first obtain your lab account, you'll notice that two CVS modules, homework and projects have already been created for you.

/
|__ homework
|__ projects

The idea is that over time, you'll build up a repository of hundreds of files, with a structure such as:

/
|__ homework
|   |__ cmsi185
|   |   |__ ...
|   |__ cmsi186
|   |   |__ ...
|   |__ cmsi281
|   |   |__ hw1.tex
|   |   |__ hw2.tex
|   |   |__ hw3.tex
|   |   |__ src
|   |   |   |__ java
|   |   |   |   |__ ...
|   |   |   |__ javascript
|   |   |       |__ ...
|   |__ cmsi282
|   |   |__ ...
|   |__ cmsi284
|   |   |__ src
|   |   |   |__ c
|   |   |       |__ hello.c
|   |   |       |__ ...
|   |   |__ ...
|   |__ cmsi386
|   |   |__ ...
|   .
|   .
|   .
|
|__ projects
    |__ halo
    |   |__ ...
    |__ scrabble
    |   |__ ...
    |__ whatever
        |__ ...

Your private repository is stored in the the directory ~/.cvs, so to make life very easy, ensure the environment variable CVSROOT is set to this value. This variable should already be set unless you've changed things yourself. In the remainder of these notes we'll assume that you haven't.

There is a special script called setup-class which will create new directories in your repository and grant access to your instructor so that he or she can extract homework submissions from your repository, and even make corrections or add notes and feedback to it. To create homework and project directories for, say, class cmsi284 and grant access to these directories for user ray invoke

~metropolis/scripts/setup-class cmsi284 ray

This creates the directories homework/cmsi284 and projects/cmsi284 and allows ray to read from them and write to them.

/
|__ homework
|   |__ cmsi284
|__ projects
    |__ cmsi284

The most common CVS tasks are these:

• Check out a module from the repository, making a copy of it on your computer's local filesystem. The checked out files constitute your "workspace", or "sandbox".
• Create new files and edit or delete files in your workspace.

• Inform CVS which of the files in your workspace you want it to track (and sometimes, which ones not to). Also inform CVS when you have deleted a workspace file and want it to remove the copy in the repository.
• Commit the changes you made in your workspace, thereby writing those changes to the repository.
• Update your workspace with the current contents of the repository. Your workspace gets out of date whenever someone else, or you on another computer, have checked in work.
• Always before committing at least, run a diff to see how your workspace differs from the repository.

Let's start by making a workspace. Create a directory called workspace in your home directory. Navigate to it, and checkout the homework/cmsi284 module.

ray@copeland:~/workspace$ cvs co homework/cmsi284
cvs checkout: Updating homework/cmsi284

This creates the directory workspace/homework/cmsi284, and marks it as being associated with your repository. Now create a directory structure for cmsi284 files, making sure to mark each of the new directories to be managed by cvs:

ray@copeland:~/workspace$ cd homework/cmsi284/
ray@copeland:~/workspace/homework/cmsi284$ mkdir src; cvs add src; cd src
Directory /afs/cs.lmu.edu/user/r/ray/.cvs/homework/cmsi284/src added to the repository
ray@copeland:~/workspace/homework/cmsi284/src$ mkdir c; cvs add c; cd c
Directory /afs/cs.lmu.edu/user/r/ray/.cvs/homework/cmsi284/src/c added to the repository

Using your favorite editor, save the following file in hello.c:

#include <stdio.h>
int main() {
    printf("Hello, world\n");
    return 0;
}

Compile and run

ray@copeland:~/workspace/homework/cmsi284/src/c$ gcc hello.c
ray@copeland:~/workspace/homework/cmsi284/src/c$ ./a.out
Hello, world

At this point you're ready to commit or "check in" your work. Only check in source code (like hello.c); never check in "derived artifacts" (like a.out).

ray@copeland:~/workspace/homework/cmsi284/src/c$ cvs add hello.c
cvs add: scheduling file `hello.c' for addition
cvs add: use `cvs commit' to add this file permanently
ray@copeland:~/workspace/homework/cmsi284/src/c$ cvs commit -m "Initial version"
cvs commit: Examining .
/afs/cs.lmu.edu/user/r/ray/.cvs/homework/cmsi284/src/c/hello.c,v  <--  hello.c
initial revision: 1.1

Now let's do something useful. Make a change to the code, something like changing the text "Hello, world" to "Hola, mundo". Do it now. We don't have to invoke cvs add this time; that was already done. But before we commit, let's get into the habit of running a diff.

ray@copeland:~/sandbox/workspace/cmsi284/src/c$ cvs diff
cvs diff: Diffing .
Index: hello.c
===================================================================
RCS file: /afs/cs.lmu.edu/user/r/ray/.cvs/homework/cmsi284/src/c/hello.c,v
retrieving revision 1.1
diff -r1.1 hello.c
3c3
<     printf("Hello, world\n");
---
>     printf("Hola, mundo\n");

That looks good, so commit:

ray@copeland:~/workspace/homework/cmsi284/src/c$ cvs commit -m "Switch to Spanish"
cvs commit: Examining .
/afs/cs.lmu.edu/user/r/ray/.cvs/homework/cmsi284/src/c/hello.c,v  <--  hello.c
new revision: 1.2; previous revision: 1.1

Now you're working with version 1.2 of this file, and the repository holds version 1.2. If someone else — or you, from another computer — checks out this file modifies it and checks in a new version, then the repository will contain version 1.3. Your local copy is now out of sync with the repository. If you worked on your out-of-sync file and tried to check in changes, CVS would complain. Before you work, you should do a cvs update. If no changes had been made you would see something like this:

ray@copeland:~/sandbox/workspace/cmsi284/src/c$ cvs update
? a.out

Here CVS is telling you that you have an unmanaged file in the workspace that it doesn't know about, which is actually as it should be. If some one had made a change (from another computer most likely), then the repsonse to the update would have been:

ray@copeland:~/sandbox/workspace/cmsi284/src/c$ cvs update
U hello.c
? a.out

Update frequently when working on teams or from multiple computers.

• Remember how you had to do cvs add to inform CVS that you wanted it to manage a file for you, before you were able to commit? When removing a file, you have to do something similar. Say cvs remove filename to disassociate the file, and then later, upon issuing cvs commit the file will be removed from the repository.
• The update command can be issued from pretty high up in the directory tree; it will update into all subdirectories.
• You can do also do a cvs commit from pretty high in the tree also to check in multiple files at once. Still, make sure you update and diff before checking in (always a good idea).

These notes do not tell you how to use the CVS client in Eclipse. Like any tool, Eclipse's CVS client automates some mundane tasks for you and allows you to do complex tasks much faster, at the price of hiding some important functionality that you'll wish you knew the moment the tools fails you or just happens not to be there. Furthermore, if you get a job in a shop that does not use Eclipse, you'll be embarassed to admit your lack of commandline knowledge. Commandline cvs is almost always faster. Eclipse pretty much only "helps" with complicated merges.

For those of you that insist on using Eclipse anyway, be prepared to make some mistakes and get confused. The following might help you get unstuck, but please note that neither the lab manager, the TAs, or the majority of the faculty will assist with Eclipse problems.

1. You must first create a repository location in Eclipse's "CVS Repository Exploring" perspective.
2. The connection type is extssh, the server is cvs.cs.lmu.edu, and your repository location is something like /afs/cs.lmu.edu/user/a/alice/.cvs.
3. When adding subdirectories and files under a directory already associated with CVS, Eclipse does the cvs add command automatically. Yes, this saves you some work, but the flip side is you will have to set things up to manually exclude files from being checked in. (Note how this differs from command line CVS, in which you manually say what to add.)
4. You do not have to invoke manual cvs remove commands, either. Simply deleting a file (from within Eclipse) is enough. When you commit, the file will be removed from the repository.
5. CVS operations are found under the "Team" menu item. The most common operations are Check Out, Synchronize, Update, and Commit. Before checking in, always go to the Team Synchronizing View and make sure everything is in order. You'll see the files that will be added, the files that will be removed, and will be able to view changed files from a fantastic graphical diff.
6. You can set up Eclipse to show you when a file has been dirtied. (This is pretty neat.)
7. While something like Eclipe's CVS client is indispensible for very large projects with complicated branching and merging requirements, it takes some getting used to. Eclipse lets you partition your work in things called projects, which you have to be very careful how you map to CVS modules. Be careful to keep these ideas distinct. You'll probably screw up a lot at first.

You really, really, really should master as much of CVS as possible. This means building up a repository and backfilling it with old assignments, tweaking old code and recommiting it, and so on. It also means outside reading and more and more practice. Some sites and books to get acquainted with include:

• CVS Home Page
• CVS at Wikipedia
• A tutorial
• An online book
• Quick Reference Card