On this page:
This document is intended for developers of the pfspd toolset. It takes only a few minutes to read it. Apart from a short generic CVS manual, this document also gives some guidelines how to use CVS for the pfspd project. All developers are expected to adhere to these guidelines to assure a similar way of working in the pfspd project.
It is assumed that the reader is familiar with the project philosophy. More generic information for developers is available in the developers guide.
CVS is a version management system based on RCS. It supports version control and configuration management and allows a team of software developers to work on a project concurrently. For more information, see the online manual. A postscript manual is available at /cadappl/cvs/1.10/doc/cvs.ps on our systems (at the NatLab). See also /cadappl/cvs/1.10/doc/cvs-paper.ps on advanced CVS use for large projects.
In general, the cvs commands can operate on a single file or on a directory. When no argument is given, the current directory is taken. When operating on a directory, cvs traverses the complete directory tree and executes on all files it finds.
This section describes the most common cvs commands.
Most commands below have a filename parameter. This may be replaced by several filenames or no filenames. The first case will execute the command for all given files, the second will recursively(!) execute the command on all files in the current directory.
To edit a file in a certain directory just type:
cvs edit filename vi filenameWhen the changes are done and tested(!) You can send your changes back to the repository by:
cvs commit -m "Document your change in this comment" filenameWhen you have edited a file and you decide not to save the changes in the repository type:
cvs unedit filename
First create the file using normal Unix procedures. Then type:
cvs add newfileNow the file is known in your local working directory but is is not known in the repository. To make it known in the repository type:
cvs commit -m "Document the purpose of this new file" newfile
To remove a file permanently, remove it from your environment first and then remove it from the repository, so use:
rm filename cvs remove filename
To rename a file, first move it the usual way, the notify cvs of the removal of the old file and adding of the new file:
mv oldfile newfile cvs remove oldfile cvs add newfile
This is not trivial using cvs. Several options exist but they all have different problems. Consult an expert to take the correct decision.
cvs release -d projectnameThis will check if you have made changes which are not known in the repository and then will ask you if it may delete the directory. Always commit or unedit all files in edit before you remove your local working directory!
To see who is currently editing a file use:
cvs editors filenameTo findout if somebody has committed a file and you do not have those changes yet use:
cvs status filenameIf a file is updated in the reporitory you will see "Status: Needs Patch" or "Status: Needs Merge" When it is "Needs Patch" you did not edit the file so you can update without conflicts. When the status is "Needs Merge" you have also edited the file so you must be carefull. To update your environment type the following (at the highest directory level):
cvs update -dThis will update all files changed. The "-d" option has the effect that new directories in the repository will also be created locally.
To do a limited update you can also specify a filename (as usual) and leave out the "-d". However, because a functional change almost always consists of multiple file changes this is usally a bad idea.
For a file with "Needs Merge" the rcs merging utility will be called and rcs will try to resolve conflicts. If you have edited a line and the same line has also changed you will get the following warning:
rcsmerge: warning: conflicts during merge cvs update: conflicts found in foo.cAll the code will be in the source file and the conflicting parts are marked with
<<<<<< >>>>>>You have to correct the conflict by hand and remove the <<<<<< >>>>>> so that cvs allows you to check in. Maybe it is wise to make a security copy of your original file before entering cvs update when you know merging is needed. When the changes are to large and you do not know how to resolve them you can undo the operation. However you still have the conflict but you have the ability to talk to the person who made the changes. A typical situation where a conflict can not be resolved is when somebody by accident has changed the file on a PC and updated it so the whole file has line feed carrage return characters at the end of each line. When that happens all the lines are in conflict.
If you have have a bug in the code which you remember that you have corrected before you can look in the logs to findout what and when things have changed by:
cvs log filenameTo look at differences of your current version and the repository type
cvs diff filenameIf you want to check against a specific version use:
cvs diff -r <tag_name> filename
Note that the use of branches and merging requires a common way of working and discipline among the development team. On one hand this is a powerful configuration mechanism. On the other hand it is a tool that easily creates a mess, just like it is easy to amputate body parts with a chainsaw...
Branches can be used to fix a bug in an old release. They can also be usefull to work simultaneously on different parts of the program, where each developer can commit his changes, without affecting other developers.
It is recommended to branch from a release. If the current state of the development is at the release point, then go to the next step. Otherwise, create a release, which may or may not be exported and distributed. It is suggested to increment the last digit in the three digit release number. The release tag name is required to register the starting point of the branch in the main trunk.
cvs tag rel_1-0-1 filelist...
To distinguish a branch tag from a release tag, a branch tag shall start with "br_" (release tags start with "rel_"). Keep in mind, that a tag name may not contain a "." character. Use a descriptive branch name.
cvs rtag -b -r rel_1-0-1 br_fixbug_325
To avoid confusion, it is recommended to checkout the branch into a separate working directory. This is identical to the initial checkout of the development tree, only the option "-r br_fixbug_325" is used.
cvs -d ... checkout -r br_bugfix_325 modulename
To prevent one large merge process when a branch is finished and should be merged back into the main trunk it is a good idea to periodically catch up with changes made (probably by other developers) in the main trunk.
To facilitate catching up, the concept of markers is used. If the latest release is "rel_1-0-1" the main trunk may be tagged later with tags like "rel_1-0-1-a", "rel_1-0-1-b", etc. This way, defined merging points are available for merging to branches.
Suppose we are working on a branch, and the latest catch-up was done with marker "b" on the main trunk. We now want to catch-up uptil marker "d":
cvs update -j rel_1-0-1-b -j rel_1-0-1-d (LABELS STRICTLY IN THIS ORDER!)
cvs commit -m "Catch-up with main trunk rel_1-0-1-b upto rel_1-0-1-d"
For the very first catch-up on a branch the first "-j" option should be left out. For example if the first catch-up was with marker "b", we would have executed the following update command:
cvs update -j rel_1-0-1-b
To keep things as clear as possible we only allow one merge from a branch to the main trunk. A branch may end in two diferent way: either we stop working on it (end of experiment), or we merge the changes into the main trunk. After this no further changes are done on the branch.
To merge all changes made in a branch into the main trunk execute the following:
cvs update -j br_fixbug_325
cvs commit -m "Merged branch br_... into the main trunk"
cvs tag rel_1-0-1-xfiles/dirs to be tagged are "Readme.txt", "foo.sh", "setup.sh", "Make.env.*", "src", "doc", and others depending on the application.
Authors: Bram Riemens Robert Jan Schutten Martijn van Balen
This page is hosted by
Copyright (c) KONINKLIJKE PHILIPS ELECTRONICS N.V. 2000-2006
Philips Research Laboratories, Eindhoven, The Netherlands
CVS id: $Id: cvs.html,v 1.2 2006/01/27 08:44:42 riemens Exp $