Maximizing Your Use of CVS

Maximizing Your Use of CVS Dan York Director of Training Mitel Networks Corporation Network Server Solutions Group (formerly e-smith, inc.) July 25, 2001 Ottawa Linux Symposium Ottawa, Ontario, Canada 25-28 July 2001 2001 Dan York

Overview Overview Basic Usage Monitoring Information Keyword Expansion Hacking the Repository Client Configuration Branching and Merging Watches CVS and RPM Add-ons to CVS Troubleshooting What is CVS? Concurrent Versions System is the dominant version control system used in the open source/free software world. Based on client-server architecture, with clients available for many operating systems. Uses a merging model where changes from multiple developers are merged together, versus a locking model where only one developer at a time can change a file Allows for use over secure (ssh) connections Also supports anonymous, read-only connections How does CVS work? A CVS repository exists on a server somewhere. Users check out a working copy onto their local system. After changes are made to files in the local working copy, a user will commit those changes to the server repository. Before starting work on the files, and periodically during work, a user will update their local working copy with changes that others have made to the repository. If two people change the exact lines in a file independently, the last one to try to commit the file will receive a notice of a conflict and will have to resolve the conflict before they can commit the file. Why do people use CVS? Allows multiple people to work independently on the same set of files. Enables you to track who made what change when - and (if they wrote a coherent log entry) - why they made that change. Provides central location for all source code. Tracks the history of a project over time. Allows changes to be easily reversed. By its nature, creates redundant backups of code. (Everyone's working copy is a full copy of the original.) What do people use CVS for? Basically any collection of files, including: Software development Documentation projects Web sites

Basic Usage CVS Command All CVS commands are in the form of:

cvs <global options> command <command options>

Typical global options might include: -d path-to-repository Path to CVS repository -q Quiet mode - suppress info messages -Q Very quiet mode - suppress all msgs except errors -z number Compression level - 0 to 9. Typically -z3 Typical command options might include: -r revnum or tagname Use the revision number or tag name -D date Use the revision no later than this date -k flag Determines how to perform keyword expansion CVSROOT CVS commands need to know where the CVS repository is that they need to access. Once the working copy is checked out, the repository location is stored in a file Root inside of the CVS subdirectory of each directory of your working copy. Until the working copy is available - and with some CVS commands - you have to tell the commands where the repository is located. Two methods: Set the CVSROOT environment variable to the repository location. In the Linux bash shell, this can be done with one of the following examples: $ export CVSROOT=/home/cvsroot $ export CVSROOT= dyork@mail.e-smith.com:/home/e-smith/files/ibays/cvsroot Supply the -d global option to a CVS command, as in: cvs -d dyork@mail.e-smith.com:/home/e-smith/files/ibays/cvsroot co documentation Log Messages Meaningful log entries are critical to others being able to understand what changes have been made. Bad: "Made a whole bunch of changes" Good: "Updated ReadFile function to support XML format. Added '-d' command-line option to allow choice of delimiter." Can be entered in editor during checkin process. (Uses $EDITOR env variable to determine editor to use.) Can also be entered on command-line using -m option cvs ci -m "Added new section to documentation on using blades." userguide.sgml Dates in CVS In any command or option that requires a date, CVS understands a number of different formats, including: ISO Standard: YYYY-MM-DD HH:MM Relative: yesterday, tomorrow, today, 3 days ago, 2 years ago, etc. Email Standard: DD Month YYYY, as in 28 Aug 2001. Per RFC 822. Other formats: including MM/DD/YYYY used in U.S. CVS uses UTC for all dates. When you use a relative date ('today', '3 days ago') be aware that that day starts at midnight (UTC). Creating a Repository Before you can use CVS, you need to have access to a repository somewhere on some server. It can be on your local system. Once you have a repository, you then create modules inside that repository and do not need to again create a new repository. To create a new repository, follow these steps: Choose a directory for a location of your repository, such as /home/cvsroot As root, execute cvs -d dir init Check the group permissions on the CVS repository directory to be sure that users are able to import modules into the repository. (Suggest you create a group called 'cvsusers', give group write permission to repository and assign appropriate users to group.) Importing a Module Once you have access to a repository, you need to import one or more modules for people to use. cd into directory containing files to be imported. Entire directory tree will be imported into CVS. cvs import modulename vendortag initialtag Example: Checking Out a Module Before checking out module, you should be in the directory in which you want the module to be. Checkout will create a directory inside of your current directory. cvs co modulename Example: Committing Changes After changes have been made, you need to commit changes to repository. cvs commit filenames "commit" often abbreviated as "ci" (check-in) If filenames are omitted, CVS scans current directory and all subdirectories and commits all modified files in tree. Example: Updating Changes Before working on files in your local working copy, and from time to time during your work, you need to update your copy with changes that others have made to the repository. Example: $ cvs update cvs update: Updating . U Makefile M hello.py $ Here Makefile has been updated with changes and hello.py has been modified locally (i.e. there are changes in the local working copy that have not yet been committed to the repository. However, regular cvs update does not include new directories, nor does it remove files that are no longer needed. Need to supply -d to add directories and -P to "prune" files that are no longer necessary, as in the example: $ cvs update -dP Dealing With Conflict Two users independently change the same line. First user commits change with no problem. Second user goes to commit change and cannot: $ cvs ci -m "Changed first print statement to be more specific." hello.py cvs commit: Up-to-date check failed for `hello.py' cvs [commit aborted]: correct above errors first! $ Second user needs to update, and will see conflict note on doing so: $ cvs update cvs update: Updating . RCS file: /home/cvsroot/hello/hello.py,v retrieving revision 1.9 retrieving revision 1.10 Merging differences between 1.9 and 1.10 into hello.py rcsmerge: warning: conflicts during merge cvs update: conflicts found in hello.py C hello.py $ Second user must now edit the file, find the conflict markers and decide which text to keep (hopefully in communication with first user): ", string >>>>>>> 1.10 ]]> Local version is first, followed by "=======", followed by repository version. File with corrected changes must now be committed. Adding Files Two stage process: Add file using "cvs add": $ cvs add Makefile cvs add: scheduling file `Makefile' for addition cvs add: use 'cvs commit' to add this file permanently $ Can supply as many filenames as you wish and can use wildcards. Commit the addition of files: Directories need to be added first, before files in that directory can be added. Many files can be added before a single commit. Removing Files Like add, two stage process: first use cvs remove and then commit the changes. One "gotcha" - file must be removed from directory first: $ cvs remove test.py cvs remove: file `test.py' still in working directory cvs remove: 1 file exists; remove it first $ rm test.py $ cvs remove test.py cvs remove: scheduling `test.py' for removal cvs remove: use 'cvs commit' to remove this file permanently $ Solution is to use -f option which will remove the file and schedule it for removal from the repository: $ cvs remove -f test.py cvs remove: scheduling `test.py' for removal cvs remove: use 'cvs commit' to remove this file permanently $ If you mistakenly remove a file and have not yet committed the change, use cvs add to retrieve file: $ cvs add test.py U test.py cvs add: test.py, version 1.1, resurrected $ Comparing Files cvs diff will compare a file (or files) from the local directory with the version(s) in the repository. Can be used with -r option to compare specific revisions or tags of a file. Example: count = 0 11c12,13 < print letter --- > print " " * count, letter > count = count + 1 $]]> Can be used with -c or -u to provide other types of diff outputs. Using Tags As each file is committed, it is assigned a revision number. All files in the repository will have a different revision number depending upon how many times it has been committed. The revision number is per file. At major milestones, you might want to flag all files at the revision point that they are currently at. CVS uses tags to accomplish this. Only restriction on tag names is that they cannot contain spaces or the period "." character. cvs tag tagname filenames If no filenames are supplied, all files in module are tagged with the tagname. Example: $ cvs tag Release-1-0 cvs tag: Tagging . T Makefile T README T hello.py $ Tag names can then be used in place of revision numbers in checkout, update and export commands. Switching Between Versions If you want to go back to a previous version of a file or project, you can revert either a single file, a group of files, or the entire directory tree. Using cvs update -r file(s) to a specific revision or tag. (Hence the emphasis on using tags.) Example: $ cvs update -r Release-1-0 cvs update: Updating . U README U hello.py $ cvs status hello.py =================================================================== File: hello.py Status: Up-to-date Working revision: 1.4 Tue Jun 12 14:25:35 2001 Repository revision: 1.4 /home/cvsroot/hello/hello.py,v Sticky Tag: Release-1-0 (revision: 1.4) Sticky Date: (none) Sticky Options: (none) $ Using -A option will update file(s) to the most recent version and without any options. Example: $ cvs update -A cvs update: Updating . U README U hello.py $ cvs status hello.py =================================================================== File: hello.py Status: Up-to-date Working revision: 1.7 Tue Jun 12 14:26:36 2001 Repository revision: 1.7 /home/cvsroot/hello/hello.py,v Sticky Tag: (none) Sticky Date: (none) Sticky Options: (none) $ Note that instead of tags and revision numbers, you can use the cvs update -D command with a date. Tags are strongly recommended instead! Exporting from CVS When you want to package a program for distribution, you can export directory from CVS into another directory. For instance, that directory could then be packaged using tar or zip. You must supply a tag name (using -r) or a date (using -D) cvs export -r tagname -d target-dir-name modulename If you use dates and want changes from today, it is best to use -D tomorrow because CVS "days" start at midnight. (So "-D today" does not get any changes made today after midnight.) Remote Access Two forms: pserver - allows separate list of users from shell accounts, but is incredibly insecure ssh - requires shell account but uses secure connection Requires that you set CVS_RSH environment variable to ssh, as in: Other modes of access such as Kerberos are possible.

Monitoring Information cvs status Displays the status of a file, or, if no filename provided, displays status of all files in local working copy. Example: With -v option, will also show tags assigned to file. cvs log Displays log messages associated with a file or files. (If no files given, log info for all files will be shown.) With -r option, shows you log message for particular revision or tag. Can show log entries between revisions using ":" between numbers. (Note there is no space between -r and numbers.) Example: $ cvs log -r1.76:1.78 userguide.sgml With -h option, shows only "header" info. With -wuser option, shows only log entries by that userid. (Note there is no space between -w and the userid.) cvs annotate Shows listing of who modified each line, when it was modified and in which version the last modification first appeared. Example: Can be used with -r or -D to look at file at a certain revision/tag or date. cvs history Gives you historical information on repository versus on individual files. Common flags include -e (show everything) and -a (for all users). Example: Other common options include: -c Report only on commits. -m modulename Show information for only that module -o Show list of modules checked out -t tagname Show history since tagname -u user Entries for a specific user

Keyword Expansion Possible Keywords Allows CVS to automagically update information inside your file Possible keywords include: Author $Author: dyork $ Date $Date: 2001/06/13 20:15:52 $ Id $Id: maximizing-cvs.xml,v 1.11 2001/06/13 20:15:52 dyork Exp $ Header Longer version of Id. Log Log entries. Note that subsequent entries will be appended to the area and the characters before the keyword (i.e. comment characters) will be preserved. Revision $Revision: 1.11 $ Source $Source: /home/e-smith/files/ibays/cvsroot/files/presos/cvs/maximizing-cvs/maximizing-cvs.xml,v $ Inserted simply by typing in keyword surrounded by '$' signs. Flags to Modify Expansion Sometimes you do not want to expand keywords (binary files!) or you just want the value instead of the keyword (exporting) Need to supply -k flag to command. Possible values include: b Binary mode. No keyword expansion or newline conversion. k Keyword-only mode. Just the name of the keyword and no value. v Value-only mode. All keywords are completely replaced with their values. Note: This mode strips out the "$"'s around the keyword and they will no longer be expanded. For example, in each version the "Id" keyword will be different. If you do not want to see the Id lines in a diff, use a line similar to: $ cvs diff -r 1.104 -r 1.105 -kk userguide.sgml

Hacking the Repository Checking Out CVSROOT Inside of the repository, there is CVSROOT directory which contains CVS configuration information. Permissions should be restricted so that only limited number of (trusted!) users can check out directory. (If a user does not have write permission for the dir, they cannot check it out.) Not all files in CVSROOT dir are checked out. Some, like history remain only on the server. After modification, when you commit changes, administrative databases are rebuilt with your modifications. Why You Would Do This Generating an email after each commit (loginfo) Flagging file types as binary (cvswrappers) Running a file through a pre-processing script prior to the commit (commitinfo) Segmenting a module so people do not have to check out the entire module (modules) Performing some action when the tag command is executed (taginfo) Creating a standard template for log messages (rcsinfo) Common Syntax Most of the repository files, especially those ending in info have the same syntax:

regular-expression command/file

When change is made matching regex, the command is executed or the file is read. Regex may be simply name of module. It will then match any file inside of that module. Two special cases supported by most, but not all, info files: DEFAULT - will be executed if no other match is found. ALL - will be executed in addition to other matches. Sometimes can have multiple ALL lines. Commit Emails Can have each commit send an email to an address with the log message and files affected. Modify loginfo, since this is affecting the log messages. Example: > /home/cvsroot/CVSROOT/commitlog ]]> As show above, you could execute some other script as well. Restricting Keyword Expansion CVS assumes that all files are plain text files. As each file is committed, keywords are expanded and newlines are converted. This can be a bad thing if the file is in fact a binary format! You can restrict the filename extensions to be expanded in cvswrappers. Example: *.gif -k 'b' *.jpg -k 'b' *.pdf -k 'b' Can also be used to specify how to merge or copy a file, or to apply a filter to a file type. Pre-commit Processing Using the commitinfo file, it is possible to perform pre-processing on a file before it is committed to the repository. Example: documentation/*.sgml /home/cvsroot/CVSROOT/validate-sgml Can be used to validate syntax or check whether it compiles correctly. If the function called exits with a non-zero status, the commit is aborted. Segmenting a Module If you have a very large module, you might want to allow users to check out only a portion of the module, possibly as small as a few files. Conversely, you might want to allow someone to check out several modules at once. The modules file has the format:

modulename directory-path

where directory-path is a path relative to the top level of the CVS repository. If files are included after directory path, only those files will be checked out. Examples: manual documentation/manual manual-only documentation/manual userguide.sgml Using an ampersand (&) will allow you to incorporate other modules into your new module. Using -a will create an alias (when you check out module, it will retain original name(s)). all &documentation &training doc -a documentation Tag Processing The taginfo file is checked whenever the cvs tag command is executed. Similar to commitinfo, file contains regex and program to execute. Program is called with tag name, operation (add, del or mov), the module/directory path, and the filenames and revision numbers for all files being tagged. One possible use would be to create a program which keeps track of all tags used in a repository. Using Templates You can create a default template that is loaded into the editor when someone commits (without using -m switch). For instance, it could have a line for a bug id, comments and name of reviewer. Steps to use a template are: Create a text file with the template text in it and add it to repository. Modify rcsinfo to have a regex and full pathname on server to template files: hello /home/cvsroot/CVSROOT/hello.tmpl DEFAULT /home/cvsroot/CVSROOT/default.tmpl Commit changes to rcsinfo and addition of template. Note that remote users may need to check out module again to obtain templates. Conformance to templates can be performed through using the verifymsg file to execute some script on the log message. Results: BUG ID: CHANGE: REVIEWED BY: CVS: ---------------------------------------------------------------------- CVS: Enter Log. Lines beginning with `CVS:' are removed automatically CVS: Other Files checkoutlist Used to list files such as templates that are not part of "standard" CVSROOT that should also be included whenever CVSROOT is checked out from repository. config (Rarely) used to set a few repository-wide variables. editinfo - obsolete notify Used by watches (discussed later) to notify users. passwd Used by (insecure) pserver for user authentication.

Client Configuration .cvsrc Located in your home directory. Includes default options that you want to pass to cvs commands. As an example: The .cvsrc file can be ignored (if you want to override options that are in the file) by using the -f global option on the cvs command. (ex. cvs -f update) .cvsignore Can be created in each directory inside of a CVS working copy. Contains regular expressions that match file or directory names. CVS ignores files matching those expressions when performing commands such as cvs update. Result is that you do not see the "?" before files not in repository. Example: If there are some that you always want to ignore, you can create cvsignore (without the leading '.') in the CVSROOT part of the repository. .cvswrappers Can be created in each directory inside of a working copy. Allows you to indicate certain files that should be treated in a specific way with regard to keyword expansion. Typically used if CVSROOT/cvswrappers is not specific enough for your needs (or you do not have the ability to change it). Example: *.gif -k 'b' *.pdf -k 'b'

Branching and Merging Why Use Branches? You have a stable version of code available and are continuing development on a new version. Someone reports a bug in the stable version that you would like to fix and release without releasing all your new (and possibly unstable) changes. You would like to try out some changes that may be be disruptive to the rest of the code. You would like to test them independently of the main code base and then (perhaps) merge them in with the main code once they have been debugged. Branches do not have to be merged back in to the main development stream. You can simply have dead branches. (Example: Someone finds a typo in an old version of a manual. You branch the files, fix and release the change. In the meantime, you have changed the text in the new version and so this change will never need to be incorporated.) Creating a Branch - Scenario #1 You want to create a branch from the current code base (to try out a new feature). Three step process: Tag the existing code base prior to the branch so that you can go back to it if you need to: $ cvs tag Release-2-1 cvs tag: Tagging . T Makefile T README T hello.py $ Use the cvs tag -b command to create a new branch: $ cvs tag -b Release-2-1-branch cvs tag: Tagging . T Makefile T README T hello.py $ Update your working copy to used the new branch: $ cvs update -r Release-2-1-branch cvs update: Updating . $ cvs status hello.py =================================================================== File: hello.py Status: Up-to-date Working revision: 1.7 Tue Jun 12 13:36:09 2001 Repository revision: 1.7 /home/cvsroot/hello/hello.py,v Sticky Tag: Release-2-1-branch (branch: 1.7.2) Sticky Date: (none) Sticky Options: (none) $ Creating a Branch - Scenario #2 You want to create a branch from a previous revision of the code base (to fix an issue in a previous version). Three step process: Revert your working copy to the previous version (Hopefully you tagged it at that time!): $ cvs update -r Release-1-0 cvs update: Updating . U README U hello.py $ cvs status hello.py =================================================================== File: hello.py Status: Up-to-date Working revision: 1.4 Tue Jun 12 14:12:42 2001 Repository revision: 1.4 /home/cvsroot/hello/hello.py,v Sticky Tag: Release-1-0 (revision: 1.4) Sticky Date: (none) Sticky Options: (none) $ Use the cvs tag -b command to create a new branch: $ cvs tag -b Release-1-0-branch cvs tag: Tagging . T Makefile T README T hello.py $ Update your working copy to used the new branch: $ cvs update -r Release-1-0-branch cvs update: Updating . $ cvs status hello.py =================================================================== File: hello.py Status: Up-to-date Working revision: 1.4 Tue Jun 12 14:12:42 2001 Repository revision: 1.4 /home/cvsroot/hello/hello.py,v Sticky Tag: Release-1-0-branch (branch: 1.4.2) Sticky Date: (none) Sticky Options: (none) $ Working with Branches Once your working copy is updated to a branch, just use CVS as you normally would. Only difference you will see is that revision numbers are 4 sets of digits instead of two. (Branch from revision 1.4 yields branch revisions of 1.4.2.1) Example: $ cvs status hello.py =================================================================== File: hello.py Status: Up-to-date Working revision: 1.4.2.1 Tue Jun 12 14:30:36 2001 Repository revision: 1.4.2.1 /home/cvsroot/hello/hello.py,v Sticky Tag: Release-1-0-branch (branch: 1.4.2) Sticky Date: (none) Sticky Options: (none) $ You can switch between branch and main trunk simply by using the update command on your working copy. Checking Out a Branch As an alternative to updating a working copy, you could check out a branch into a separate directory. You can use -d option to cvs co to put branch into separate directory. Example: Merging From a Branch - The Simple Case In the case where you have tried out a new feature and want to merge it with the main trunk, follow this process: Tag the branch with a meaningful tag (we'll see why later): $ cvs tag Release-2-1-branch-fix1 cvs tag: Tagging . T Makefile T README T hello.py $ Update your working copy to the most recent copy of the main trunk: $ cvs update -A cvs update: Updating . U hello.py $ Use cvs update -j to "join" the branch into the trunk: $ cvs update -j Release-2-1-branch-fix1 cvs update: Updating . RCS file: /home/cvsroot/hello/hello.py,v retrieving revision 1.7 retrieving revision 1.7.2.1 Merging differences between 1.7 and 1.7.2.1 into hello.py $ Resolve any conflicts and commit any changes. The main trunk now includes the changes from the branch. Merging With Keywords One caution - if you use CVS keywords in your files, they will of course be different. On the merge of the branch into the trunk, you will see conflict messages for the files where the keywords conflict. To avoid these conflicts, update with just the keywords themselves and not their values using -kk: $ cvs update -kk -j Release-2-1-fix1 Continuing With The Branch But what if you want to continue developments in the branch? Two choices: Let the old branch simply die, and follow the process earlier to create a new branch ("Release-2-1-branch2"). Simple approach, but leaves other branches around. (No big deal from CVS' point of view.) Continue development in the existing branch. A couple of issues here: If you subsequently try to merge using the method described earlier, all changes in branch will be merged - creating conflicts with changes that have already been merged. Solution is to use a tag before each merge and then (in the main trunk), use multiple -j options: $update -j Release-2-1-branch-fix1 -j Release-2-1-branch-fix2 Changes made to the main trunk will not be incorporated into the branch. To include those changes, update in the branch copy using the special tag HEAD that refers to the tip of the main trunk. $ cvs update -kk -j HEAD cvs update: Updating . U Makefile U README RCS file: /home/cvsroot/hello/README,v retrieving revision 1.7 retrieving revision 1.8 Merging differences between 1.7 and 1.8 into README U hello.py RCS file: /home/cvsroot/hello/hello.py,v retrieving revision 1.7 retrieving revision 1.9 Merging differences between 1.7 and 1.9 into hello.py rcsmerge: warning: conflicts during merge $ Resolve conflicts and commit the changes to the branch.

Watches The Case for Watches CVS allows multiple users to work on the same files simultaneously. Conflicts, if any, are found and reported at commit time. Works well and without many conflicts assuming that responsibility is clearly assigned for who is primarily responsible for what files or sections. (And also on projects where commits are infrequent.) Problems can occur with a large project under very active development when there is the potential for several developers to modify the same section of code at the same time. A way to minimize conflict is to use a feature of CVS called watches. Watches Defined When using watches, users essentially tell everyone else who might want to change the file that they are going to be working on it. Other users are notified by e-mail when the user starts to edit the file and again when the file is committed (or changes are aborted). Requires participation of all users to be effective. Getting Set Up to Use Watches Before you can start using watches, you need to modify at least two files in the CVSROOT directory of repository. In the notify file, you need to establish how the notifications will be sent out. Typically, the entry is simply: ALL mail %s -s "CVS notification" The change then needs to be committed to the repository. You also need to modify the users file to include the CVS userid of each user and their corresponding e-mail address: dyork:dyork@e-smith.com With a new repository, you may need to create this file. You then need to add and commit the file. If you are adding the file, you also need to add it to the checkoutlist file in CVSROOT. Watching Files For each file that you want to be notified about, you enter the following command: $ cvs watch add filename If you omit the filename(s), a watch will be added for all files in the directory tree. There are three actions you can be notified about: commit, edit, and unedit. For instance, to be notified only about commits, you enter the following command: $ cvs watch add -a commit filename You can see who is watching a file with cvs watchers: $ cvs watchers hello.py hello.py dyork edit unedit commit fred commit $ Without a filename, it shows all files that are being watched. Removing a Watch If you no longer want to watch a file, you can remove a watch with: $ cvs watch remove filename Like add, without filenames it will assume the directory tree. Working with Watched Files If you are using watches, you need to take the following steps: Before editing a file, issue the command cvs edit: $ cvs edit hello.py $ Notification is then sent to all people who have an edit watch set. When you commit the file, notification will be sent to all watchers. If you decide you want to abort your changes, you can issue the cvs unedit command. Note that in doing so your file will be reverted back to the state of the last commit. Example: $ cvs unedit hello.py hello.py has been modified; revert changes? y $ Notification will be sent to all of those with an unedit watch. You can see who is editing a file with cvs editors command. Enforcing Watches Nothing forces users to trigger watches. They can choose to not issue the cvs edit command therefore watchers will only be notified when a commit occurs. A way to remind users is to use cvs watch on to set file to read-only by default: $ cvs watch on filename(s) As before, without filename(s), it modifies all files in dir tree. Does not change other users' working copies immediately, but file(s) will be changed to "read-only" in the future whenever: a) the module is checked out; b) a user commits the file. In order to change from "read-only" to "read-write" the user needs to issue the cvs edit command for that file. File will have changed back to "read-only" after it is committed. Nothing prevents user from manually changing file with chmod. To turn off "read-only" settings, use cvs watch off

CVS and RPM The Problem You take a program (foo-2.0) and make a series of modifications to it. Now you want to package up your modifications in a form that can be distributed to others. The "CVS way" is to import the original package and make all of your modifications in CVS. Then do a cvs export of the repository at a certain moment in time (date, revision, tag) and package that exported directory. The advantage is that you have everything under version control and can see logs of who has worked on it, revert patches, branch, etc. The "RPM way" is to have a pristing source of the original package, and then apply one or more patches to the original source. The advantage is that you can see precisely what has been modified in the patch files, and can potentially drop in a new version and patch that newer version. The Solution When doing the import of the original package, use a meaningful start tag, as in: $ cvs import -m "Initial import into CVS" foo dyork foo-version-2-0 Use CVS as you would normally do for the development of the files. At packaging time, first tag the repository with a meaningful tag: $ cvs tag Release-2-1 At packaging time, first extract a copy of the original version (if you do not have a tarball somewhere else): $ cvs export -r foo-version-2-0 -d foo-2.0 foo Use cvs rdiff to generate a patch file: foo-2.0.patch.20010611 ]]> Subsequent patches can be generated using the new tag as the first tag in the sequence. (i.e. "-r Release-2-1 -r Release-2-2")

Add-ons to CVS cvsweb http://stud.fh-heilbronn.de/~zeller/cgi/cvsweb.cgi/ Web interface for browsing through a repository. viewcvs http://viewcvs.sourceforge.net/ Originally based on cvsweb, but re-done in python and with more options. cvsgraph http://www.akhphd.au.dk/~bertho/cvsgraph/ Tool to create a graphical view of the evolution of your file(s). Example:

Troubleshooting Tracing the Connection To troubleshoot a CVS session, you can trace the connection between the CVS client and server. cvs -t command main loop with CVSROOT=lodestar2.dyndns.org:/home/e-smith/files/ibays/cvsroot/files -> Starting server: ssh lodestar2.dyndns.org cvs server dyork@lodestar2.dyndns.org's password: -> Sending file `maximizing-cvs.xml' to server -> unlink_file(CVS/Entries.Static) -> unlink_file(CVS/Entries.Static) S-> unlink_file(CVS/Entries.Static) S-> unlink_file(./CVS/Entries.Static) S-> rename(CVS/Entries.Backup,CVS/Entries) S-> unlink_file(CVS/Entries.Log) S-> checkout (/home/e-smith/files/ibays/cvsroot/files/presos/cvs/maximizing-cvs/maximizing-cvs.xml,v, 1.2, , (function)) S-> unlink_file(graphics/CVS/Entries.Static) M maximizing-cvs.xml -> unlink_file(CVS/Entries.Static) S-> rename(CVS/Entries.Backup,CVS/Entries) S-> unlink_file(CVS/Entries.Log) S-> rename(CVS/Entries.Backup,CVS/Entries) S-> unlink_file(CVS/Entries.Log) $ ]]> Using CVS_CLIENT_LOG You can also log exactly what gets sent by the client and by the server. Set the CVS_CLIENT_LOG environment variable to the base filename you want to use. Logs will be created as basename.in and basename.out Example: $ export CVS_CLIENT_LOG=log20010610 $ cvs -Q update $ ls log* log20010610.in log20010610.out $ Note that this only works with connections to remote repositories. It will not work if commands occur on same machine. History File Permissions With some earlier versions of CVS (prior to 1.11), the history file was created with the wrong permissions when the repository is initialized. Because of this, users cannot import or check out modules to/from the repository. You must connect to the server and (usually as root) change the permissions so that everyone has read and write access to the history file. File Permissions All files in repository are set to be read-only. If a file is imported or added with execute (x) permission, that will be retained. However, if you later want to make a file executable, you will need to change the permissions on the actual file in the repository on the server. Suggest enabling (as root) the "set group id" bit on module in server repository so that all subsequent files and directories get created with the appropriate group permissions: # cd /home/cvsroot # chgrp cvsusers documentation # chmod g+s documentation Note that you may need the -R flag if you are doing this after module already contains data. Changing Log Messages Finally, a tip on dealing with human troubleshooting... if someone writes an "inappropriate" log message, or makes a mistake with a log message, it can be modified with the cvs admin command with -m command. Example: Change takes place immediately and is irreversible.

Conclusion Resources CVS Home Page: http://www.cvshome.org/ "Cederqvist" CVS user manual: http://www.cvshome.org/docs/manual/cvs.html Pascal Molli's pages: http://www.loria.fr/~molli/cvs-index.html Books: CVS Pocket Reference, by Gregor N. Purdy, published by O'Reilly & Associates, August 2000 Open Source Development with CVS, by Karl Fogel, published by CoriolisOpen Press, 1999, http://cvs.red-bean.com Questions? Contact Information Dan York, Director of Training, e-smith, inc. dyork@e-smith.com dyork@Lodestar2.com +1-613-263-4312 This presentation will be available from: http://www.lodestar2.com/talks/cvs/