Last updated: 7 Jan 2006

Using CVS

Here is some basic information about using CVS, with some specific information for our setup, which does not use the pserver but relies on ssh to provide access to the server. That means that you use your INSTTECH login account and password to access the repository server, whether it be for your own repository or for a team repository.

Please note that a "module" and "project" are the same concept and the terms are used interchangeably. They are generally represented as a file system's directory of files and subdirectories. However, we will use "module" here to indicate a named collection of information stored in the CVS repository.

Also note that the default behavior of CVS is to work with source code, which means files that you can easily read in an editor. Binary files require more vigilance and an extra option (e.g., -kb) on the cvs command to handle.

Here is the Official Wiki Version of the CVS Manual, which contains an overview and sample CVS session, as well as details on all of the commands an options.

Initializing CVS for Individual Use

You only need to do this once. Team accounts already have CVS set up.

1. login in to repos.insttech.washington.edu with ssh and your INSTTECH login password

2. create a cvs directory:

   	  mkdir ~/cvs
   	  

3. initialize the repository:

   	  cvs -d ~/cvs init
   	  

4. Remove group permissions so others can't read or modify your repository:

   	  chmod g-w ~/cvs/CVSROOT
   	  

Using CVS Tools

These instructions use a command shell and the cvs command to use CVS; there are GUI tools (e.g., jCVS, Eclipse) that may make maintaining your repository easier. However, the GUI tools usually wrap and invoke the underlying cvs subcommands to do the job, so these instructions are fairly universal. The GUI tools require the same information as the cvs command or the environment variables it can use, but often the information is broken down into smaller chunks like "SSH Server" and "repository path".

When a cvs command runs, it will prompt you for a password -- this is your INSTTECH login password, not your UW email password.

Basically, you need to tell CVS what you will use to communicate with it, then specify enough information to allow it to connect to the server. For a command shell, set up an environment variable called "CVS_RSH" and point it to the ssh command. Setting up the "CVSROOT" environment variable saves typing a cumbersome connection string for every cvs command.

Note that you should set up the following environment variables prior to running any cvs command (but only once time in a command shell -- the shell remembers environment variables until it is closed). You could also place the name-value information in a Linux .bashrc file, or on Windows in "My Computer/Properties/Advanced/Environment Variables" for more permanent setting.

• Windows

  This is a lab workstation-specific path to ssh2.exe; yours at home may vary.

  set CVS_RSH=c:\Program Files\UWICK\SSH Communications Security\SSH Secure Shell\ssh2.exe
  set CVSROOT=:ext:uwnetid@repos.insttech.washington.edu:/home/INSTTECH/cvsid/cvs
          

• Unix

  The path to ssh is how we set it up on Linux, and the command to set the environment variables is bash-specific. Another version of Unix and another shell interpreter may require you to change these lines.

  export CVS_RSH=/usr/bin/ssh
  export CVSROOT=:ext:uwnetid@repos.insttech.washington.edu:/home/INSTTECH/cvsid/cvs
          

where uwnetid is your UW Net ID, and cvsid depends on whether or not you are using a team account: if you are, then it is the team account name; if you are not, it is your UW Net ID.

Creating a New Module

1. Create a new folder of information to put under version control

   A new folder is created because some CVS tools delete the originals after checking them in (or "importing" them). It makes sense to do this, since the master copy should always reside on the server and you should check out only what you need. However, for the initial setup, in case something goes wrong, it is good to work with a copy.

   Create a folder on your h: drive and either place a dummy file into it or copy your project files that you want to add to the repository into it. (CVS requires that at least one file be added to the repository before you can start using it.)

   For example: Create a folder named H:\Winter2006\tcss342\
           and place an empty text file called dummy.txt in the folder.
           

2. Import the files into a "module"

   You will need a name for this module, something that describes this collection of files and folders. The import subcommand will take the contents of the current directory and import them into CVS.

   For example, let's say you call it tcss342:

           cd /d H:\Winter2006\tcss342
           cvs import myproj vendid versionid
           

   where "vendid" can be anything (e.g., "win2006"), and "versionid" can be anything (e.g., "start").

Checking Out a Module

1. Prepare to checkout: move or delete the folder you have created

   The process of checking out a module will recreate or overwrite folders.

   • If you added a dummy file, delete your local copy of the directory (the one you created on your h: drive, h:\winter2006\tcss342).

   • If instead you copied real project files, then just rename your project folder.

2. Check out the module to get a working directory

   This provides you with a working directory in which you may make changes.

           cd /d H:\win2006
           cvs checkout tcss342
           

Adding Files to the Module

Once a module is set up, you normally want to checkout the whole thing as a working directory, or some part of it, work with all or part of the checked out material, then discard or check them back in ("commit") or add new material.

1. To add all files and folders:

         cvs commit tcss342
         

   Note: you may not want to add all files or folders to the module. It is not recommended to add *.class files, or other compiled code, or any other extra files created by an IDE that can be regenerated from the source.

2. Adding a folder
   1. Create the new folder in your working copy of the module

      Let's call it homework1, and put the file test.java inside it.

   2. Add the folder to the module

              cd tcss342
              cvs add tcss342 homework1
              cvs add homework1/test.java
              cvs commit -m "Early version" homework1/test.java
              

      The first add merely makes it known that the new directory is to be placed under version control. The second add puts the only file in that directory under version control, but does not check it in; other users can't see it. Only the final commit actually puts it into the module and makes it accessible to others.

      Another important point is that "add" is not recursive -- each individual file in a directory has to be explicitly added. Use "import" to do a recursive add.

Viewing Changes to a File Using Diff

If you are unsure of what changes were made on a modified file, (you don't remember changing it) or you want to see changes between older revisions, use the name of the file in question to compare your local file with the same remote revision, using the "diff" subcommand.

    cvs diff homework1\test.java
    

Getting a Clean Copy of a File

If after running a diff on a file, you discovered that the file was changed accidentally, and you want to get rid of all the changes without checking them in, then use the name of the file and the "update" subcommand.

	cvs update -C homework1/test.java
	

This will wipe all of your changes and replace it with the fresh version from the server. If you selected the wrong file, or you decided later that you did want those changes, cvs has made a copy of you file for you. If you were working on "test.java" (version 1.2) and you decided to get the clean copy of the file, you will notice a new file called .#test.java.1.2 which is a back-up copy of the file you just wiped.

Checking in Modified Files

After you have modified a file and you are satisfied with the changes, save your file, and run the "update" subcommand.

    cvs update homework1
    

This will verify with the server that these files have actually changed, and if you are working on shared code, it will check to see if anyone had changed any of the files between the time you first checked them out and now. Your changed files will show up preceded by 'M'.

If there are not any conflicts (read the next section if your file is marked with 'C'), commit the files. Add an appropriate log message.

    cvs commit -m "Final version" homework1/test.java
    

These log messages are what show up when you are looking for older versions of your code.

Conflict Resolution

If you performed an update on a file or folder, and any of your files were marked with a 'C', there is a conflict between updates that needs to be resolved.

1. Open the file, and search for a section that looks like the following:

   Original File:

   public class DieRoll
   {
       public int rollDie(int face)
       {
           return (int)(Math.random() * face) + 1;
       }
   }
   	

   File with Conflict:

   public class DieRoll
   {
   <<<<<<< DieRoll.java
       public static double rollDie(int face)
   =======
       public int rollDie(int face)
   >>>>>>> 1.2
       {
           return (double)(Math.random() * face) + 1;
       }
   }
   	

2. Remove the incorrect section, and the diff flags, and re-update the file.

   public class DieRoll
   {
       public int rollDie(int face)
       {
           return (double)(Math.random() * face) + 1;
       }
   }
   
   	

The Rest of the Story

There is a lot more to CVS than is presented here, including a whole other category concerning the administration of a CVS server (which can be enlightening to read, but is not necessary to use our CVS server). Please refer to the Official Wiki Version of the CVS Manual for details.

Change Log