OSU Mixing Group's guide to CVS

Jody M. Klymak mailto:jklymak@uvic.ca

OSU Mixing Group's guide to CVS.
Introduction.
What is CVS?
Why do we need Version Control?
Why CVS?
How it works
Getting Started.
Installing the CVS executable:
Getting the Repository.
Day-to-day use
Updating the repository.
"Committing" an edited file
"Adding" a new file to the repository.
Some notes on committing and adding
Adding new subdirectories to the repository.
Conflict Resolution.
When to Commit
Some Gravy.
How do I get at old versions?

Introduction

What is CVS?

CVS is a software version control system. It allows users to get a collection of software files from a public repository, edit them, and then commit your changes to the repository. Changes are stored such that any previous versions can be easily retrieved in case a bug is introduced.

Why do we need Version Control?

  1. Supplies a central place to get all m-files that we use for data processing.
  2. Provides a simple mechanism to edit those files and distribute your changes to the rest of the group.
  3. Allows us to revert the m-files to any state in their history in case a bug was introduced.

Why CVS?

CVS is similar to a number of other software products that allow version control (i.e. RCS, MS SourceSafe etc), however it had some minor advantages:

  1. free and small
  2. widely used in the free software community
  3. Compatible with UNIX and Macs (just in case)

On major advantage is that it does not "lock" files in the repository. Many version control systems require that you check a file out if you want to make changes to it. After you have made the changes, you must check the file in again. In the meantime, no one else can make changes to the file. While this sounds like a good idea, it actually is a big nuisance; rarely do two people edit the same file at the same time, so checking out and checking in all the time becomes very annoying.

A second major advantage is that the repository is read-only. You checkout a copy of the whole repository, put it somewhere in your personal directory where you can do whatever you want with it. If you want some of your changes to be shared, then you check those changes in, no harm is done if you don't do so however. I'm sure that some of us will only checkout files, and never bother to check any in (this is the way most free-software gets used as well 99.9% of the users just check out the latest version and never contribute changes).

A third major advantage is that CVS maintains a log for each file of changes made, and who made the changes. This will help greatly in maintaining the software.

How it works

CVS maintains a "repository" of our public software on a single machine in our network. This repository is read-only and should not be messed with. Nor should it be referenced for things like MatLab paths; in fact, the files in the repository are not useable except by CVS.

Instead the user checks out a copy of the repository into a "working directory". Many people can get copies of the repository and use them. If one of the users discovers a bug or improves a file, then they "commit" their change to the repository. The old version of the file is not lost, but is superseded by the new one. Users checking out the repository will now get the new version of the file.

Getting Started

Installing the CVS executable:

CVS is distributed as a single executable cvs.exe , and should be run from the command line. For now it is at \\mserver\backups\cvsnt\cvs.exe. Either copy cvs.exe into your windows path (not MatLab path), or edit your windows path to include \\mserver\backups\cvsnt\.

Second, CVS needs to know where the repository is. Add the environment variable CVSROOT to your environment. CVSROOT should be //mserver/backups/cvsroot. NOTE: CVS is a UNIX-ish program so please specify forward slashes for this variable

To do this, open Control Panel-System-Advanced-Environment Variables. Under System Variables press New. Under Variable Name enter CVSROOT and under Variable Value enter \\mserver\backups\cvsroot.

Documentation

While you are there, you may wish to take a look at the CVS manual. It's a little lengthy, but explains all this in gruesome detail.

Getting the Repository

Now we are ready to run cvs. First we want to get a "working copy" of the repository. The repository that I have made is called "mixingsoftware". Suppose you would like to put it under c:\test\. What will result is a directory structure under c:\test\mixingsoftware that is exactly the same as the one in the repository.

  1. Open your favourite shell. I like using the MatLab shell. But if you use another shell (i.e. Command shell) be sure to not include the leading exclamation point I use in the examples below.
  2. cd c:\test
  3. !cvs checkout mixingsoftware

After a few seconds this should leave you with the latest copy of the mixing software in c:\test\mixingsoftware. You can now use these files are you would any other files in your operating system. You can add c:\test\mixingsoftware\general to your MatLab path. There are a few things to note.

  1. If you run "cvs checkout" from a directory it puts whatever you asked into the current directory. CVS doesn't care where you put things. So be a little careful when doing this you can make a mess.
  2. Moving files out of the directory structure you create and using them elsewhere is fine, but you will lose the advantage of using CVS. i.e. being able to add your changes to the public repository. If you are used to keeping "cal" and "cal_readonly" in c:\matlabR12\toolbox\local\ then feel free to unpack mixingsoftware there (though I dislike putting things in the c:\matlabr12 directory).
  3. You will notice that each subdirectory under your working copy of mixingsoftware has a subdirectory "CVS". This contains information that CVS needs to synchronize your changes with the public repository.

Day-to-day use

Updating the repository

Suppose you have already checked out the repository as described above into a working directory c:\mydir\mixingsoftware. Perhaps you have edited some files in your working directory. Then Sasha announces the latest and greatest version of raw_load.m and a new file calc_epsilon_so_very_very_general.m You could have Sasha mail you these files, and then you could extract them from your mail message into the directory, or preferably, Sasha could check them into the CVS repository and you could "update" your working repository. To do this:

  1. cd c:\mydir
    1. be sure to do this or you will end up making a new working directory somewhere unexpected.
  2. !cvs update mixingsoftware

This will check your working directory against the repository for changes and fetch you the newest files. Note that any files you edited will stay the same, i.e. they will not be overwritten by the repository files. Therefore, if you have made changes but are not ready to share them, they will not be erased.

"Committing" an edited file

Suppose that Sasha is ready to release his new copy of mixingsoftware/marlcham/raw_load.m to the world. He performs a "commit":

1. cd c:/mydir/mixingsoftware/marlcham/

2. !cvs commit -m "Fixed raw_load bug number 1" raw_load.m

Now the public repository has the new version of raw_load.m. CVS assigns it a version number. The "-m" option is a message that is put into the CVS log describing the problem. Please use this to briefly describe what you changed. This is one of the major advantages of using a CVS to keep track of changes.

"Adding" a new file to the repository

Now Sasha wants to add mixingsoftware/marlcham/calc_epsilon_so_very_very_general.m to the repository. This is a new file that did not exist before, but he wants to share with everyone. CVS is kind of dumb you cannot simply "commit" this new file. Instead, you must "add" it first, and then "commit" it.

1. cd c:/mydir/mixingsoftware/marlcham/

2. !cvs add -m "Initial add" calc_epsilon_so_very_very_general.m

a. add tells CVS that there is a new file to be kept track of. It will not let you commit a file if you do not add it first.

3. !cvs commit -m "Initial commit"calc_epsilon_so_very_very_general.m

Some notes on committing and adding

  1. You can add or commit more than one file at a time.
  2. You can commit a whole subdirectory. I.e:

a. cd c:/mydir/mixingsoftware

b. !cvs commit -m "commiting marlcham changes" marlcham

c. This will commit any files that you have changed in marlcham to the repository. A directory commit is also recursive, so any subdirectories are also committed.

4. You cannot recursively "add" subdirectories. See below if you need to do this.

Adding new subdirectories to the repository

Suppose you have created a new directory that you would like to put under mixingsoftware. Lets call it biosonics (to use an example which may become imminent). In your working directory you should have c:\mydir\mixingsoftware\biosonics. Now you are ready to share with everyone else. To do this you run "import"

  1. cd c:\mydir\mixingsoftware\biosonics
  2. !cvs import -m "mixingsoftware/biosonics" mixingsoftware/biosonics mixinggroup biosonics
  3. now remove c:\mydir\mixingsoftware\biosonics (perhaps back it up somewhere else)
  4. cd c:\mydir
  5. !cvs checkout mixingsoftware/bisonics

This will create a new subdirectory mixingsoftware/biosonics in the repository and anyone checking out mixingsoftware will get a copy of it. The last two arguments ("mixinggroup biosonics") are superfluous and need only be strings of some sort.

Checking the Log

It is easy to check the log of a file in the repository:

!cvs log mixingsoftware/marlcham/raw_load.m

Conflict Resolution

Because files are not locked, it is entirely likely that two of us will make changes to the same file and then try to check them into the repository. Suppose that Sasha and Gunnar check out mixingsoftware into their own working directories on Monday. They have identical copies. Two days later, Sasha modifies and commits mixingsoftware/marlcham/raw_load.m. Three days later, Gunnar also commits a change to raw_load.m. CVS handles this by not committing Gunnar's change until Gunnar examines the differences. To do this it merges Sasha's changes with Gunnar's in Gunnar's working directory. Gunnar then must go through and find the changes and make certain they are compatible with his changes.

This should not be as difficult as it sounds, and I don't expect it to happen too often. However, if you become confused when your file will not commit, this may be why.

When to Commit

Don't commit every time you save your file that will make the repository needlessly large and complicated. Commit when you have a working version of an m-file that you want to share with the group. Send a message to us if it is important enough to merit everyone updating their working directory.

Some Gravy

You know how the Mathworks has that cool header:

% $Revision: 1.23 $ $Date: 2000/07/31 18:27:43 $

Well, you can too. Under your initial comment, place the following:

% $Revision$ $Date$ $Author$

CVS will automatically fill in the version number etc.

I haven't set all the files to include this, but if you edit one, please feel free to put this in.

How do I get at old versions?

This is not too hard, but for now see me. I'm not sure how easy it is to re-integrate things when this is done.