1. A primer to using CVS Rob M Baxter, Stephen P Booth, Joachim Hein

2. M02:Using CVS2 Outline Using CVS –Existing repository –Finding out about its modules –Getting code in and out –Getting information about the repository contents –Tagging code versions Advanced topics –Starting a repository –Starting a module –Branching & merging Getting help

3. M02:Using CVS3 Why CVS? Why use CVS –Its open source and very widely used –It works on collections of files (modules) –It can access remote repositories across networks –Many/most IDE environments support CVS as a backend version control system –We like it. CVS weak points –Automatic file versions numbers are per-file not per-project –Change logs are per-file not per-project –The subversion system addresses these issues and may eventually replace CVS but its not as widespread as CVS yet.

4. M02:Using CVS4 CVS commands I CVS consists of one program (called cvs) that can perform many operations. –Usage: cvs [cvs-options] command [command-options and argments] The command keyword specifies which operation you want –Some commands have alternative names The cvs-options control the general behaviour of cvs The command-options are specific to the command A small number of commands goes a long way

5. M02:Using CVS5 CVS commands II Most commands take a list of files/directories/modules as an argument but default to the current directory/module When operating on a directory/module all sub-directories are automatically included in the operation. Use cvs --help for more information

6. M02:Using CVS6 Starting work with CVS CVS stores file versions in a Repository –A Repository is a directory tree. –Your first step is to tell CVS where your repository is: $CVSROOT –csh and tcsh users: setenv CVSROOT /home/myid/cvsroot –sh and bash users: export CVSROOT=/home/myid/cvsroot – Can also use -d flag You take a working copy of the files you need to edit –Working copies store Repository and version information in a sub-directory called CVS. –Once you have a working copy it “remembers” where the Repository is.

7. M02:Using CVS7 Repository on a remote computer/network Repository on a remote computer: use $CVS_RSH to tell CVS how to access ( ssh is a good idea) export CVS_RSH=ssh export \ CVSROOT=':ext: @training.epcc.ed.ac.uk:/home/ /c vsroot' This will query password, unless you set up an ssh-agent If cvs is not on the default PATH on remote machine export CVS_SERVER=/opt/local/bin/cvs There are other mechanisms but this is the most common

8. M02:Using CVS8 Other configuration Choose your preferred editor, for when CVS needs input: –export CVSEDITOR="emacs –nw" –If $ CVSEDITOR is unset, it checks: $ EDITOR Consider putting into.profile,.bashrc,... CVS also has a set of configuration files. –These are stored in the Repository in a module called CVSROOT –Unfortunate naming convention as CVSROOT != $CVSROOT –To modify configuration files to need to: –Check out working copy –Edit files –Commit changes to the Repository –More on configuration files later..

9. M02:Using CVS9 CVS repository CVSROOT contains CVS admin files –CVSROOT  $CVSROOT Projects are stored in subdirectories *,v-files contain the history of each file Removed files get moved to the “Attic” Manipulate repository via cvs commands only Defining modules helps

10. M02:Using CVS10 Modules Many CVS commands work on modules –Modules are useful collections of files At its simplest a module may just be a directory tree More complex modules can also be defined by using the configuration files. – However the default behaviour is to look for a directory tree in the Repository with the same name as the module.

11. M02:Using CVS11 Ready to go: Changing and retrieving files cvs co –“Check out” –Extracts private working versions of files in module –Only use this the first time you create a working copy! cvs ci [files] –“Check in” –“Publishes” changed working files in the Repository –Creates new file version numbers cvs update [files] –Retrieves most up-to-date versions from Repository –“Re-syncs” working files with Repository files –Doesn’t lose changes to working files –Only needed for multiple developer projects

12. M02:Using CVS12 cvs co cvs co project/src/db –Extracts private working versions from all files beneath directory $CVSROOT/project/src/db/ –Puts them in subdirectory./project/src/db/ cvs co my_module –Extracts working versions from whatever collection of directories or files my_module refers to (in $CVSROOT/CVSROOT/modules,v ) –Puts them in subdirectory./my_module/ –(Rem: unless -d specified in modules file) –If no entry in modules file, defaults to first ‘directory’ behaviour –Checks out all files in $CVSROOT/my_module/ Recommendation: use modules

13. M02:Using CVS13 cvs co Also creates a CVS subdirectory –e.g../project/src/db/CVS This contains admin files for this working copy –Entries, Root, Repository –Internal CVS files –Ignore them; certainly don’t delete them :-) Presence of this subdirectory usually tells you that this directory is under CVS control

14. M02:Using CVS14 cvs ci cvs ci [files] –For each specified file that has been changed (or each changed file in the current module): –Creates a new revision version in the Repository –Adds a new “delta” to each,v file with a new revision number –Prompts for a “log message” to describe changes –Automatically updates your working versions –Acts recursive if no files specified If someone got there first, CVS will complain –If someone else has committed changes to the same files, CVS will not let you overwrite them –Must do an “update” first to merge any changes into your working copy –May have to resolve conflicts

15. M02:Using CVS15 cvs update cvs update [file1] [file2] –Retrieves latest checked-in versions of files if they differ from your working ones (but doesn’t overwrite your changes) –Reports on each file as it does it –U file : “updated”, for unchanged or missing working files –A file : “added”, for working files you’ve add ’ed but not checked in –R file : “removed”, for files you’ve remove ’ed but not checked in –M file : “modified”, for changed working files which have merged successfully with any Repository changes –C file : “conflict”, for changed working files whose changes conflict with Repository changes (someone got there before you...) –? file : a file CVS knows nothing about –If you want to go back to your most recent version, delete the file and run update

16. M02:Using CVS16 cvs update The only result to worry about is “conflict” The conflicting file now contains lines like <<<<<<< filename working version lines ======= Repository version lines >>>>>>> VN where VN is the Repository version number Resolve this by hand editing & cvs ci –May need to talk to author of version VN !

17. M02:Using CVS17 cvs update -d Normally cvs update updates existing files and directories only Use -d option to get files and directories added (by others): cvs update –d Consider what you need: –Not using –d when needed: you loose out on latest additions –Using –d when not needed: you might drown in stuff

18. M02:Using CVS18 Adding and removing files cvs add –Marks files to be added to the current module in the Repository –Must use this to let CVS know of new files cvs remove –Marks files to be removed from the current module in the Repository –Files must be deleted from the working directory first Both commands only “flag” files –Adds/removes not completed until cvs ci

19. M02:Using CVS19 cvs add Schedule files for addition: cvs add init.c map.c fcbridge.F Can also add new subdirectories: bash$ cvs add subdir bash$ cd subdir bash$ cvs add Must add subdir before adding files Important: –Only after cvs ci will these be in the Repository!

20. M02:Using CVS20 cvs remove cvs remove testHarness.c hacks.c Must actually delete working files first bash$ rm oldfile bash$ cvs remove oldfile –Otherwise CVS complains (nice safety net!) To cvs remove subdirs, they must be empty bash$ rm subdir/ bash$ cvs remove subdir –Does an implicit cvs remove on subdir/ Don’t forget the check in! Removed files get moved to the “ Attic ” –They are not deleted from the repository (Thanks goodness!)

21. M02:Using CVS21 Getting CVS information cvs status [files] –Gives a useful summary of status of [files] (or all files in the module) –working and Repository revisions –whether working file is modified, add ’ed, remove ’d –status of any symbolic tags cvs log [files] –Lists revision history and check-in comments for each version of [files] cvs diff [files] –Lists all differences between current working versions and last- checked-out versions of files in standard Unix diff format

22. M02:Using CVS22 cvs status cvs status gui.h cvs status: Examining. ============================================================ File: gui.h Status: Locally Modified Working revision: 1.3 Thu Nov 21 11:33:51 1996 Repository revision: 1.3 /home/me/CVS/project/include/gui.h,v Sticky Tag: (none) Sticky Date: (none) Sticky Options: (none) Useful before a ci or update

23. M02:Using CVS23 cvs log cvs log init.c RCS file: /home/me/CVS/project/src/db/init.c,v Working file: init.c head: 1.18 branch: locks: strict access list: symbolic names: start: 1.1.1.1 project: 1.1.1 keyword substitution: kv total revisions: 19; selected revisions: 19 description: ---------------------------- revision 1.18...

24. M02:Using CVS24 cvs log ---------------------------- revision 1.18 date: 1996/12/04 15:16:28; author: fred; state: Exp; lines: +2 -1 Added init code for new Freezers table. ---------------------------- revision 1.17 date: 1996/11/27 09:05:56; author: sally; state: Exp; lines: +4 -1 Changes for addition of simple.c. ---------------------------- revision 1.16 date: 1996/10/01 11:14:32; author: sally; state: Exp; lines: +7 -2 Fixed file error bug. Failure to open files led to attempting to destroy a table not yet created. Hence, if you get the filename wrong you get a bus error :-(. ----------------------------...

25. M02:Using CVS25 cvs diff cvs diff db.h Index: db.h ====================================================== RCS file: /home/me/CVS/project/include/db.h,v retrieving revision 1.3 diff -r1.3 db.h 57,58c57,58 #define DB_TOOSMALL-26 > #define DB_NOSPACE-25 The ‘ ’ lines are the working version

26. M02:Using CVS26 cvs diff cvs diff answers the question –“I’m working on version 1.3; what changes have I made to it?” You can also ask –“I’m working on version 1.3; has anyone checked in any new versions, and if so, how does my working version differ from the latest one?” –Use cvs diff -r HEAD –HEAD is a special symbolic name for the latest version in the Repository, the “head of the tree”

27. M02:Using CVS27 cvs release You can use the UNIX rm to remove a working copy –No checks whether there are non-committed changes Saver to use: cvs release –d –Goes into directory checks for uncommited changes –Deletes the directory and all its files and sub-directories if successful –Warning: Still no check for added files and directories which have not been “ cvs add ” to the repository!

28. M02:Using CVS28 Tags CVS can attach a tag to a set of files (e.g. release version) Useful to retrieve this set of files in this form at a later stage Recipe: –Go to the module base directory of your local working copy –Issue: cvs tag –c –This will attach the tag to all the files of the module (incl. subdirs) –The –c option enables checking for locally modified files To retrieve a tagged module with name mymodule: cvs co –r mymodule –Only do this to make a read-only copy, you need to make a branch to edit an old version

29. M02:Using CVS29 More advanced topics

30. M02:Using CVS30 How to define explicit modules (recipe) Modules are defined in CVSROOT/modules inside the repository To look at the file and manipulate it, get it out of the repository: cvs co CVSROOT/modules This will create a directory CVSROOT with a file modules inside – do it in a sensible place Step into CVSROOT and display/edit the modules file Once done, commit change(s) with cvs ci modules Step out of CVSROOT and remove it with: cvs release –d CVSROOT

31. M02:Using CVS31 How does a module file look? Think alias! A simple module file: # this is a comment project1 project2 pro2subA project2/subdirA 1 st column: name of module (alias) and placement of contents 2 nd column: position in repository More advanced: myproject –d thesubpro project5/subdirB/subsubdirV will place contents of project5/subdirB/subsubdirV in thesubpro

32. M02:Using CVS32 Creating a CVS Repository Choose where you want the Repository to live Set the CVSROOT environment variable –bash$ export CVSROOT=$HOME/MY_CVS Run cvs init What does this do? –Creates the directory specified by $CVSROOT –Creates the subdirectory of administrative files, $CVSROOT/CVSROOT Your CVS Repository is now ready for use

33. M02:Using CVS33 Starting a project Typically two cases: –Someone hand you a source you have to work with –Place source in a “nice” directory –You start your own project from scratch –Start the project in a “nice” directory, a simple file will do for the beginning Use cvs import to place it into the repository Define a module Check that ok, by checking in out into a different location –Consider rename of the original If ok: –Important: Work on a checked out version –Seriously consider deleting the original source

34. M02:Using CVS34 cvs import –Creates directories in Repository: $CVSROOT/ –Adds all files from current working directory, recursively –Can use options to tell CVS to ignore certain files –Tags are symbolic names for this “baseline” import adds to the Repository but does not provide a proper working version... Before further hacking, must cvs co a working version

35. M02:Using CVS35 cvs import A standard “recipe” is: –cd ~/my_projects/project1 –cvs import project1 project1 baseline Rem: Imports code to $CVSROOT/project1 –[add new entry to modules file if desired] –cd.. –mv project1 project1.old –cvs co project1 Rem: Extracts a proper working version with CVS admin directory –rm -rf project1.old

36. M02:Using CVS36 Branches Some people love them others hate them (management) Can be useful: –Bug fixes for old releases –Private parallel universe to develop a (set of) new feature(s) –The set of features should be limited (single feature?) –Once tested and ok: merge into the main source –Recommendation: Merged branches should die (multiple merges messy) Don’t use for different code versions –Different branches don’t “inherit” from each other –e.g. fixes to shared I/O routine –Use: switches, compiler directives, build procedures etc.

37. M02:Using CVS37 What is a branch Consider a single file –At Rev 1.2: Branch created  1.2.2.1 –The branch evolved, total of three versions –The trunk evolved independently –At Rev 1.5: Branch merged into trunk –Advise: Don’t touch the branch after merge CVS works on modules not files: –Branches affect different files at different revision numbers –Use branch tags (symbolic names)

38. M02:Using CVS38 Working with branches To create a branch –Go into base directory of working copy –Ensure: the checked out version is the right one! –Issue: cvs tag –b –Remark: This will not get you into the branch No difference between working with: tag & branch-tag: –cvs co –r my_module –cvs update –r [file] Gets you into the branch (“Beam me up Scotty”) This is also “sticky”

39. M02:Using CVS39 Merging Needs care and communication inside the project group Recipe –Check out the branch you want to merge into (normally the trunk): cvs co my_module –Step into it: cd my_module –Merge the side branch named “ dev-branch ” cvs update –j dev-branch –Crucial: Resolve conflicts and check that it works –Only once happy: cvs ci Remarks: –Merges can add files –Merges can move files to the “Attic”

40. M02:Using CVS40 Help, further info CVS inbuilt help for subcommands: cvs –H ci cvs –H co Documentation: P. Cederqvist et al.: “Version Management with CVS”, various formats, extensive (PDF: 173 pages) http://ximbiot.com/cvs/manual/

41. M02:Using CVS41 Summary CVS is a tool –Removes the need for multiple copies of similar code –Modules ease working with extensive sources –Introduces security net to code development –Easy to go back –Repository in different location from working version –Enable multiple people to work on a single source CVS is no replacement for communication, policies and management A few core commands will go a long way –ci, co, update, add, remove, diff, status, log