Archiving your work with CVS

1. Archiving your workwith CVS Jon Arrowood 2001-Nov-16

2. Overview • Version control • What is it? • Basic concepts • Why should I use it? • One particular method: “Concurrent Versions System”, or CVS • Setting up a new project • Manipulating a project • Where to go for further help

3. Version Control -- What is it? • An organized method of keeping track of the history of a set of files • The idea: • A set of files is checked out of the main repository to a directory, some are modified, then checked back in • Sets of files can be tagged with release names for an easy way to get groups of files (for example, “Release 2.0”). • Old versions of files can be retrieved at any time • Different versions can exist on different branches

4. Version Control -- Basic Concepts The basic concepts are: • checking in revisions • tagging releases • branching releases • merging from branch to branch

5. x.cpp y.cpp z.cpp Ver. 1 Ver. 1 Ver. 1 Version Control - Checking in Revisions • For example, a repository begins with three files: x.cpp, y.cpp, z.cpp. • The three files are checked out. • After changes, z.cpp is updated, followed by x.cpp, then z.cpp again. Ver. 2 Ver. 2 Ver. 3

6. x.cpp y.cpp z.cpp Ver. 1 Ver. 1 Ver. 1 Ver. 2 Ver. 2 Ver. 2 Ver. 3 Ver. 3 REL_2_0 Version Control -- Tagging Releases • Take the repository we were just using. • Tag the latest versions as “Rel_2_0” • Further changes can be made at will • We can easily go back to REL_2_0 at any time

7. rel_2_0 pre_rel_3_0 rel_2_1 rel_2_1 Version Control -- Branching/Merging • You’ve finished Release 2.0, and are working on pre-3.0 • You find a bug in 2.0 that needs fixing now • Create a new branch, tag as Release 2.1 • If required, merge changes into 3.0 track • Note that the boxes above refer to sets of tagged files, not individual files

8. Version Control -- Various concepts • Version control is not just for C/C++ code! • Great for LaTeX • Matlab files • etc. • Files are saved as a base file, and diffs to give other versions • saves lots disk space • binary files must be checked in differently than text files • Watch out for End-Of-Lines if mixing Win32 & Unix • Lines end w/ “\r\n” in Win32 text files, but just “\n” in Unix • Refer to manuals on how your specific software handles this.

9. Version Control -- Software Choices Many different Version Control systems exist All have basically the same functionality • Concurrent Versions Systems (CVS) • Available for any conceivable platform • Freely available • Mediocre GUI available (WinCVS) • Microsoft Visual SourceSafe (VSS) • Win32 only • Easy to use GUI • Perforce • Similar to VSS, but cross platform • Expensive (free, however, if <= 2 developers) • RCS • Old Unix software, replaced by CVS

10. Version Control -- Why use it? #1 Excellent when project has > 1 person • Easy to merge in changes from an external group • Everyone has access to latest version • Easy to ensure that latest version works • can use automated tool (such as “tinderbox”) to verify that each version works, if you’ve written testing tools. • Automated notification to other developers when files are updated • Even if you’re the only user, you can have multiple simultaneous copies to work on

11. Version Control -- Why use it? #2 Makes backups very easy • Repository is in a single location • Backups as easy as TGZ’ing or ZIP’ing one directory • Easily moved to a new machine caveat: I have no idea if this is true with VSS, but probably?

12. Version Control -- Why use it? #3 Great way to keep track of small tests • When trying something new in your research, you can branch for new ideas • Easy to return months later to a particular test • Test code can later be merged into your main code in a straightforward manner • No more naming-work-directories-with-today’s-date

13. One particular piece of software: CVS CVS is particularly nice: • freely available • already installed on systems in CSIP • ported to almost every platform • has a Win32/Unix/Mac GUI • very popular

14. Using CVS: Initializing a repository • Requires an environment variable, giving the location of the repository: [jon@yamwb]$ export CVSROOT=$HOME/cvsroot • Initializing repository is then done by: [jon@yamwb]$ cvs init • Running init on an already existing repository won’t harm it

15. Using CVS: Starting a new project • Begin with a directory of existing code (say it’s called “project1”) [jon@yamwb]$ ls project1/ [jon@yamwb]$ cd project1 [jon@yamwb]$ cvs import project1 jon start <an editor will pop up forcing you to add comments> [jon@yamwb]$ cd .. [jon@yamwb]$ mv project1 project1-to-be-deleted [jon@yamwb]$ cvs checkout project1 [jon@yamwb]$ ls project1/ project1-to-be-deleted/ • The new “project1” directory is now ready for use with CVS

16. Using CVS: • Always use “cvs checkout” before working on the files (of course, save the orig directory until you’re sure you’re using CVS correctly!) • Inside of the new project1 directory, you’ll find a subdirectory named “CVS”. [jon@yamwb]$ ls project1-to-be-deleted file1 file2 file3 [jon@yamwb]$ ls project1 CVS/ file1 file2 file3 [jon@yamwb]$ • This directory contains the history info for the local files, so comparisons can be made to the repository later on

17. Using CVS: Committing file revisions • Checkout a project, change some files • When you’ve made a significant change that you’d like saved simply run [jon@yamwb]$ cvs commit or [jon@yamwb]$ cvs commit file1 file2 • Default action is to check in any locally modified files in the current, or lower, directories.

18. Using CVS: Adding files to a project • Go inside a project directory already under CVS control (ie, it has a “CVS/” subdirectory) • Create some new_file [jon@yamwb]$ cd project1 [jon@yamwb]$ ls CVS/ file1 file2 file3 [jon@yamwb]$ echo “foo” > bar [jon@yamwb]$ cvs add bar [jon@yamwb]$ cvs commit bar <an editor will pop up forcing you to add comments> • require “-kb” qualifier if files were binary: cvs add -kb binary_file

19. Using CVS: Tagging a release • To tag a release [jon@yamwb]$ cd project1 [jon@yamwb]$ cvs tag REL_1_0 Note: only the checked-in files are tagged, if you’ve locally modified files, you must ‘commit’ them first. • To retrieve this version of the code, at any time [jon@yamwb]$ cvs checkout -r REL_1_0 project1 [jon@yamwb]$ ls project1/ Note that you can have different versions of the same project checked out in different places.

20. Using CVS: Branching/Merging • Beyond the scope of this talk, look in the extensive online docs at www.cvshome.org • One hint: mistakes can be made when branching or merging. Always backup your CVSROOT repository before major operations.

21. Using CVS: Utilities • cvs status -v some_file • lists all tags associated with a file • cvs diff some_file • generates the diff between your local version of some_file and the current repository version • cvs diff -r REL_TAG some_file • generates the diff between your local version and an arbitrary repository version

22. Version Control -- Review The basic concepts are: • initializing a repository • importing an initial directory • changing files, then committing those changes • adding new files, then committing them • tagging releases • creating branches • merging from branch to branch

23. Using CVS: Various • CVS works over networks, so you can keep your cvsroot at school, but checkout from home. • Secure shell easily used: export CVS_RSH=ssh • Files/directories are never completely removed. If they existed once, you might always ask for them back.

24. Resources for CVS • www.cvshome.org • for generic info on CVS • www.wincvs.org • for Win32/Linux/Mac GUIs for CVS • webCVS (can’t find a site for it right now…) • a CGI script that lets you browse your repository with Netscape. Only for browsing -- you can’t change anything