A Short Introduction to CVS

1. A Short Introduction to CVS Dan Negrut Simulation-Based Engineering Lab Dept. of Mechanical Engineering University of Wisconsin

2. Acknowledgement • Presentation put together using a variety of Web sources

3. 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.

4. 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

5. So why is backup easy if using 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

6. 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)

7. 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.

8. How does CVS store multiple 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)

9. 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

10. 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.

11. CVS 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

12. 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

13. CVS as a tool to manage collaboration • 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 7th 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

14. CVS as a tool to manage 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 inmechanism 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

15. 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

16. 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

18. 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

19. 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 • Create the directory asme2007: >> cd >> mkdir asme2007 • 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". • cd back out of the new empty asme2007 directory and remove it >> cd >> rm -fr asme2007 • Now check out a working copy of the Module >> cvs checkout asme2007 • You are now good to go, cd into this directory and start adding files to this module, see next slide…

20. 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

21. 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

22. 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 asme2007 cvs checkout: Updating asme2007 U asme2007/aps.bst U asme2007/apssamp.tex U asme2007/paper.tex U asme2007/related_macros.tex U asme2007/paper.bib cvs checkout: Updating asme2007/Images U asme2007/Images/5_5_fine_gridColor.ps U asme2007/Images/5_5_fine_meshColor.ps U asme2007/Images/5_5_var_gridColor.ps U asme2007/Images/5_5_var_meshColor.ps U asme2007/Images/5by5_recon_setup.eps U asme2007/Images/5by5_slab_all.eps U asme2007/Images/5by5_slab_err.eps U asme2007/Images/compFlowProposal.eps U asme2007/Images/jazz13_5_iso_color.eps U asme2007/Images/jazz13_7_iso_color.eps U asme2007/Images/reconstructionIdea.eps

23. 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…

24. 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

25. 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”)

26. 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”

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

28. 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

29. Tkdiff produced report Diffs between version 4 and 5 nicely colored

30. 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

31. 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

32. Cvsweb produced page • See output produced by cvsweb at http://sbel.wisc.edu/Research/nano/htm/repository.htm