Jody M. Klymak mailto:firstname.lastname@example.org
OSU Mixing Group's guide to CVS.
What is CVS?
Why do we need Version Control?
How it works
Installing the CVS executable:
Getting the Repository.
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.
When to Commit
How do I get at old versions?
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.
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:
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.
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.
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.
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.
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.
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.
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:
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.
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.
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
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.
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"
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.
It is easy to check the log of a file in the repository:
!cvs log mixingsoftware/marlcham/raw_load.m
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.
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.
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.
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.