A Short Introduction to CVS

Dan NegrutSimulation-Based Engineering Lab

Dept. of Mechanical Engineering

University of Wisconsin

Acknowledgement

Presentation put together using a variety of Web sources

Purpose of CVS

CVS stands for Concurrent Versions System It enables one to do easy backup of their work

This is not the primary purpose, but it’s essential in my opinion

Helps you keep organized

Enables collaboration between two or more people when using the same project resources Source files, Model files, LaTeX files, etc.

How does CVS work?How does CVS work?

The CVS repository

Most important concept to grasp to understand how CVS works

The best analogy is that of a library that holds many books, each book possibly having several chronological editions

As a library holds books, the repository stores your collection of files, each file possible having several chronological editions The repository is simply a large directory on your file system and uses special

conventions (that are irrelevant to you) to backup your information (files)

The way CVS works/operates revolves around these repository files, which you repeatedly check out and then check back in Each time you check back in a file, the repository produces a new “edition” of

that file

So why is backup easy if using So why is backup easy if using CVS?CVS?

If you use CVS, that is, have your important files under revision control, all those files can be backed up by simply backing up the repository, that is, one directory

Note that the repository keeps files that you work on and reside (are scattered) in many different directories on your PC

However, these files all have a copy stored in the repository, so backing up each night the repository will automatically back up all your important files

How does CVS work?How does CVS work? Use previous analogy with book library

You go to library, and check out a the 7th edition of Beer/Johnston/Clausen Dynamics book You take to book home, read it, and then return it

When using files instead of books, you are going to modify these files. So the scenario is like this: You check out a file from the repository, modify it, and then return it

to the repository. If you checked out the 7th version of the file, what you are going to check back will become the 8th edition of the file CVS allows you to go back immediately to *any* edition of your file

(they call it any version of your file)

How does CVS work?How does CVS work?

Where does the analogy with the book library stops?

A library is to a large extent a static entity: you cannot add the 9th edition of the Beer/Johnston/Clausen Dynamics book

The CVS repository is a dynamic entity: when you return a file (this is called checking in the file), you have modified its content and the repository generates a newer edition (version) of that file

Here are some possible reasons to modify your file You found a bug in a MATLAB source file, or You further developed a model of a NASTRAN element, or You added a new section in your LaTeX paper Etc.

How does CVS store multiple How does CVS store multiple versions of the same file?versions of the same file?

CVS has the ability to provide *any* previous version of your file

These versions of the file should therefore be stored somewhere…

Is this going to eat up a lot of disk space?

Generally not… CVS is smart enough to look at a new version that you check in, compare

it with the previous version it holds on to, and make note of the differences between the two versions

CVS only stores in the repository the original version of the file plus a sequence of changes i between version i and i+1.

One notable exception: when dealing with binary files, CVS can not apply the rule and it ends up storing the entire file This can quickly start eating up a lot of disk space… (REMEMBER THIS)

Can you mess up and break CVS?

You cannot break CVS… …as you cannot break, say, notepad.exe

CVS is simply an executable (cvs.exe) that operates on the CVS repository and checks/balances are in place to always protect the content of the repository

So in this regard it’s pretty idiot proof… …yet they say that someone immediately makes a better idiot

The only way to mess up is to actually start editing/deleting the CVS repository directly (that is, not using cvs.exe)

Recall that the CVS repository is a directory living on your machine or on the network somewhere

You do not want to touch this directory unless You know well what you are doing You have already backed it up, and have a reference to go back to if

things go south

Further remarks…

Common sense advice:

Ask someone more experienced to set up the repository for you for the first time

Don’t keep the CVS repository in your home directory or some other place where you can edit/delete it by mistake

You create the repository once, and then you actually should forget that you even have such a thing. cvs.exe (the executable) will take care of your interaction with the

repository, it serves as your agent to commit changes, check out files, etc.

CVS as a safety netCVS as a safety net When you use CVS you are always working with a copy of the

original file

The book library analogy: At library you are never given the book, you are given a copy of it…

If you spill your coffee on your copy, or tear it to pieces it doesn’t really matter, the original is safe

In a bad case scenario, you decide to take the coffee spilled version of the book and check it back into the library That’s not nice of you, since the next guy who checks out the book

(might be you…), will inherit the coffee spills No big deal though, in CVS you can always go to the version before

the coffee spill, and make that version the default again effectively making the coffee spilled version a thing of the past

Putting things in perspective…Putting things in perspective… CVS helps you keep project assets safe

Source code, models, LaTeX files, pics You can have multiple CVS repositories

It is like having more libraries in one city You can use a repository for group projects in the Lab and have a

second repository that you decide to set up to store information related to your thesis, papers, etc.

CVS works as a safety net effectively letting you undo bad decisions

Enables you work on group projects and better manage collaborative efforts

CVS as a tool to manage CVS as a tool to manage collaborationcollaboration

Going back to book library analogy, Naresh and Toby check out on Monday the book they’ve been working on, “Indian Cuisine: Easy Recipes for Party Feasts”, which is currently in its 7 th edition

Toby adds a new soup recipe and without testing (tasting) it, checks in a new edition of the book, that is, the 8th, on Wd.

Naresh adds a new spicy cookie recipe, but he also does some testing/validation of the new recipe He’s done on Th, but when he wants to check in, CVS will reject his

request. If he checks in, he’d step on the soup recipe that was meanwhile included

Naresh does an update of the book, and CVS takes his local copy and updates it with the new soup addition. Naresh now tries again to check in his copy, CVS likes the idea, and he is the author of the 9th edition of the cookbook

CVS as a tool to manage CVS as a tool to manage collaboration (cntd.)collaboration (cntd.)

Previous example is the essence of how CVS handles group projects:

If you edit a copy of a repository file while going about doing your daily job, cvs has a built in mechanism that prevents you from blissfully checking in your edits back into the repository and thus stepping on other people’s changes

Thus, before you check in something, you have to update your local copy to include the recent changes made by other people and only then CVS will respond to your request and make your copy the default version of the file in the repository (the “update then check-in” rule) This is the ground rule that makes things tick in group projects:

CVS WILL NOT LET YOU CHECK IN A FILE (LOCKS THE REPOSITORY), AND THUS MODIFY THE REPOSITORY MASTER COPY, UNLESS YOU FIRST UPDATE YOUR LOCAL COPY OF THE FILE

The mechanics of using CVS

Setting up a CVS repository Creating a module in CVS Adding/Removing a file to/from CVS Checking in a file Checking out a file Updating a file Resolving Conflicts Investigating the log associated with a file Comparing differences between file versions (native and Tkdiff) Secure CVS for remote collaboration cvsweb utility

CVS: getting started

You can download cvs from (at date of this doc): http://ftp.gnu.org/non-gnu/cvs/binary/stable/x86-woe/

Available if you install cygwin on windows (highly recommended) All examples in what follows are assumed to be carried out using the cygwin

shell Available in all standard Linux distributions

Use from command line (make sure directory where lives is in executable path)

>> cvs

Many GUI available, wincvs (www.wincvs.org) Tortoisecvs (www.tortoisecvs.org), works with InternetExplorer Command line is all you need in my opinion

CVS: initializing the repository First create a root directory for the repository (e.g. ~/cvsrootDAN)

Make CVS aware of the root directory: In csh:

setenv CVSROOT ~/cvsrootDAN In Bash, Bourne shell:

CVSROOT=~/cvsrootDAN export CVSROOT

Add the CVSROOT setting command to appropriate startup file ~/.cshrc or ~/.bashrc

Initialize the repository from command line>> cvs init

Creating a module in CVS

Say you work on an ASME conference paper for the 2007 conference and want a module that will contain all the files related to you LaTeX paper

1. Create the directory asme2007:>> cd >> mkdir asme2007

2. Change directory into the new empty directory and import it into CVS effectively creating a new Module

>> cd asme2007 >> cvs import -m “setting up my ASME 2007 conference module" asme2007 vtag rtag

- m option specifies a log message you might want to add that goes with the creation of this module

- vtag is the vendor tag (this argument is required, I never used it). Just use "vtag". - rtag is the release tag (this argument is required, I never used it). Just use "rtag".

3. cd back out of the new empty asme2007 directory and remove it >> cd>> rm -fr asme2007

4. Now check out a working copy of the Module >> cvs checkout asme2007

5. You are now good to go, cd into this directory and start adding files to this module, see next slide…

Adding a file to CVS

To add a file or directory to the project (module), first create it, then use the cvs add and cvs commit commands

From that point on, the repository starts tracking the file (“main.cpp”, in this example)

Example>> emacs main.cpp

<Type in code and then Ctrl-X Ctrl-C>

>> cvs add main.cpp

>> cvs commit –m “initial revision of driver” main.cpp

Removing a file from repository

When you want to get rid of a file from repository (like getting rid of a book from the library)

Actually, CVS never quite gets rid of it, if you want to go back and changed your mind the file it’s still hidden in the guts of CVS (in the “attic”, to be precise)

>> cvs remove –f “main.cpp”>> cvs checkin –m”decided to eliminate” main.cpp

Checking out a file or a module When you want to start

working with a file you check out a file. If the file is part of the module (asme2007), you check out the entire module and along come all the files contained in that module

>> cvs checkout main.cpp (gets you one file)>> cvs checkout asme2007 (gets you one module, with all the files it contains)

>> cvs checkout asme2007cvs checkout: Updating asme2007U asme2007/aps.bstU asme2007/apssamp.texU asme2007/paper.texU asme2007/related_macros.texU asme2007/paper.bibcvs checkout: Updating asme2007/ImagesU asme2007/Images/5_5_fine_gridColor.psU asme2007/Images/5_5_fine_meshColor.psU asme2007/Images/5_5_var_gridColor.psU asme2007/Images/5_5_var_meshColor.psU asme2007/Images/5by5_recon_setup.epsU asme2007/Images/5by5_slab_all.epsU asme2007/Images/5by5_slab_err.epsU asme2007/Images/compFlowProposal.epsU asme2007/Images/jazz13_5_iso_color.epsU asme2007/Images/jazz13_7_iso_color.epsU asme2007/Images/reconstructionIdea.eps

Checking in a file You have a local copy of the MATLAB file “driver.m”, you made

some changes, decided that they are good and should find their way in the master copy that lives in the repository

At this point you are ready to do a check in>> cvs checkin –m”contains Nick’s sparse solver modification” driver.m

Including a comment to indicate the modification that led to this version is going to pay off down the stretch when you have 30 versions of this file and can’t quite recall what you did two months ago…

Updating a file Scenario:

Monday morning Toby checked out the file “recipe.txt”, while Naresh checked it out early afternoon The version that each works on is version number 11 of that “recipe.txt”

In the evening, Toby is done and checks in his version (which becomes version 12 in the repository) He sends Naresh an email saying that he’s finished his changes are

already in the repository On Tu morning, Naresh does an update of the file to bring into his local

copy all the changes that Toby made the previous day:>> cvs update recipe.txt

Recall the “update then check-in” rule

Resolving conflicts Having to resolve conflicts is anything but fun…

Scenario: Monday morning Toby checked out the file “recipe.txt”, while

Naresh checked it out early afternoon The version that each works on is version number 11 of that file

Due to a communication hiccup, they both end up modifying the recipe for the spicy cookies

Naresh is more familiar with the recipe, checks in his changes first (repository now holds on to version 12)

Toby follows the update then check-in convention, but when he updates, his modifications of the file, conflict with Naresh’s (they both modified exactly the same part of the file “recipe.txt”)

Resolving conflicts (cntd.)

Key question: which changes should be kept? Toby’s or Naresh’s?

CVS cannot know who’s more deserving (they both are…)

It’s none of CVS’ business to decide what changes should be overwritten by the other changes

When Toby does the update, CVS will simply flag the regions of the file that conflict and it will be up to Toby and Naresh to figure out this Toby will have to clear all the flags, and since he was the one

dealing with the conflicts will have to check in what becomes version 13 of “recipe.txt”

CVS log

You can take a look at all the changes that were made to a file:>> cvs log qmat.cpp

The cvs “log” command indicates the time of the change, who made the change, and the comment provided by the person who made the change

$ cvs log qmat.cpp

RCS file: /nfs/mcs-homes64/negrut/CVSrepository/ParRec/Src/qmat.cpp,vWorking file: qmat.cpphead: 1.7branch:locks: strictaccess list:symbolic names:keyword substitution: kvtotal revisions: 7; selected revisions: 7description:----------------------------revision 1.7date: 2006-07-25 19:25:13 +0000; author: negrut; state: Exp; lines: +7 -0fixes bug in scaling of the double integral----------------------------revision 1.6date: 2006-02-07 17:35:26 +0000; author: negrut; state: Exp; lines: +1 -1cosmetics----------------------------revision 1.5date: 2006-02-06 15:42:18 +0000; author: negrut; state: Exp; lines: +24 -3finished computation of Ene----------------------------revision 1.4date: 2006-02-04 16:04:51 +0000; author: negrut; state: Exp; lines: +4 -0almost done computing kernel Ene----------------------------revision 1.3date: 2006-02-03 23:58:21 +0000; author: negrut; state: Exp; lines: +17 -18finished kernels T and K; moving on to Ene----------------------------revision 1.2date: 2006-02-02 16:07:58 +0000; author: negrut; state: Exp; lines: +29 -2support for computing 1D kernels; not there yet though----------------------------revision 1.1date: 2006-01-25 15:44:22 +0000; author: negrut; state: Exp;reorganizing the directory tree======================================================================

Comparing differences between two versions of a file

If you want to see what got modified going from revision 4 to revision 5 of the file on previous slide>> cvs –diff r1.4 r1.5 qmat.cpp

You can also use tkdiff, an utility that is freely available on the net (email me if you need a copy of the tkdiff.exe)>> tkdiff -r1.4 -r1.5 qmat.cpp

Tkdiff produced report

Diffs between version 4 and 5 nicely colored

CVS in client mode

Normally, CVS repository lives on the local file system Hard to collaborate between distributed teams

CVS can run in client-server mode Server machine runs ssh server and keeps the repository Client machine queries the server Only diffs are being sent => fast even on slow net Converts automatically MSDOX/Unix files Use it to keep source files synchronized I can help setting up a CVS client if interested

cvsweb

Perl utility distributed outside cvs but that works in conjunction with CVS to produce a web interface that allows other people to browse your CVS repository using a web browser

Contact me if interested in setting up this service

Cvsweb produced page See output produced by cvsweb athttp://sbel.wisc.edu/Research/nano/htm/repository.htm