CVS guideline - Index

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.

This section describes the most common cvs commands.

1. General information

   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.

2. Editing existing files

   To edit a file in a certain directory just type:

       cvs edit filename
       vi filename
       

   When 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" filename
       

   When you have edited a file and you decide not to save the changes in the repository type:

       cvs unedit filename
       

3. Adding a new file

   First create the file using normal Unix procedures. Then type:

       cvs add newfile
       

   Now 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
       

4. Removing a file

   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
       

5. Renaming a file

   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
       

6. Removing/renaming a directory

   This is not trivial using cvs. Several options exist but they all have different problems. Consult an expert to take the correct decision.

7. Removing your local development tree (i.e. stop/cancel development):

       cvs release -d projectname
       

   This 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!

8. Retrieving information out of the system

   To see who is currently editing a file use:

       cvs editors filename
       

   To findout if somebody has committed a file and you do not have those changes yet use:

       cvs status filename
       

   If 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 -d
       

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

   All 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 filename
       

   To look at differences of your current version and the repository type

       cvs diff filename
       

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

1. Go to the root dir of the application or module. Note that branches shall be created from the main trunk only.
2. Stop all development. Use "cvs editors" to check if anybody is still editing a file.
3. Register the branch point.

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

4. Create the branch.

   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
       

5. Checkout the branch in a separate working directory.

   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
       

6. You're in business.

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":

1. Go to the root directory of your working directory of the appropriate branch.
2. Execute:

       cvs update -j rel_1-0-1-b -j rel_1-0-1-d  (LABELS STRICTLY IN THIS ORDER!)
       

3. Proceed as usual when merging (i.e. resolve conflicts if needed, test the new software).
4. Commit the code with:

       cvs commit -m "Catch-up with main trunk rel_1-0-1-b upto rel_1-0-1-d"
       

5. Continue working on the branch as usual.

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:

1. Go to the root directory of your working directory of the main trunk.
2. Stop all development in the branch. Use "cvs editors" to check if anybody is still editing a file in the branch.
3. execute:

       cvs update -j br_fixbug_325
       

4. Proceed as usual when merging (i.e. resolve conflicts if needed, test the new software)
5. Commit the code with:

       cvs commit -m "Merged branch br_... into the main trunk"
       

6. Tag the main trunk with the next marker:

       cvs tag rel_1-0-1-x   ...  
       

   files/dirs to be tagged are "Readme.txt", "foo.sh", "setup.sh", "Make.env.*", "src", "doc", and others depending on the application.
7. Remove all working directories pointing to the branch (remember, the branch will not be changed anymore).

Authors: Bram Riemens Robert Jan Schutten Martijn van Balen

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 $