Notes on CVS: RobotCub repository
More information about CVS can be found at: www.nongnu.org/cvs
CVS is a versioning system that keeps track of a set of files as they change through the development process. Files are stored as differences from one revision to the next and numbered accordingly. You can look at the version number, request specific versions, differences between versions, etc.
Typical CVS Usage
The typical use is a very simple though. There are three operations:
checkout update commit
For using the RobotCub server details and ssh please have a look at:
To start working on the repository on Linux/Unix/command line shells (for Windows users, see the specific section on WinCVS but please keep reading this part here), use the 'checkout' command as follows:
export CVS_RSH=ssh cvs -d:ext:YOURUSERNAME@cvs.robotcub.org:/cvsroot/robotcub checkout -P iCub
the '-P' option prunes empty directories that might exist in the repository. You should see something like this on your terminal:
cvs server: Updating iCub U iCub/AUTHORS U iCub/COPYING U iCub/INSTALL U iCub/README U iCub/TODO cvs server: Updating iCub/bin U iCub/bin/dummy.txt ...
The checkout is used only once to download your initial local copy. To get in sync with changes in the repository you use the update command:
cvs update -P -d
at this point, since your local copy has already been checked out you don't need to specify the yarp root anymore. You will see something like:
cvs update: Updating iCub cvs update: Updating iCub/license
with occasional U or P entries corresponding to modified or new files. The -P and -d options are recommended to prune empty directories and download newly created directories respectevely.
Finally, if you change any of the files and you wish to commit the changes to the global repository on the server use the commit command by doing:
cvs commit -m "your commit message goes here"
which checks for modified files and tries to commit them. There are various outcomes at this point depending on the status of the repository.
- If you were the only one changing the file, then it is committed to the repository with a message telling you the new version number.
- If the file has been changed, then you are asked to perform an update before committing the file again.
- The update tries to merge your new changes with the changes from the repository. The merge is automatic but it could occasionally run into conflicts (marked by a letter C next to the file name during the update). You are told about the conflict and asked to solve it before committing the file again.
Please make sure your project and/or changes compile fine before committing to the global repository. The typical work cycle when using the versioning system is the following:
- update to the latest changes in the repository
- work hard!
- commit your changes when done, solve conflicts and commit again
If you are creating a new project, there is a special command called 'add' which creates a new folder and puts the files on the repository. For each folder you have to do:
cvs add FOLDERNAME
and only then (for example):
cvs add *.cpp
inside FOLDERNAME. This ONLY schedules an addition to the global repository, then you have to complete it with:
cvs commit -m "your commit message here"
For WinCVS users (in addition to the preceeding discussion).
Checkout: Go to Remote menu and click on 'checkout'. It opens a dialog box with various panes.
- On the 'checkout settings' pane, set the 'module name' to be 'iCub'.
- Local folder: your choice of where to place the local copy (avoid folders with space characters)
- CVSROOT, click on the ellipsis on the right, you get another dialog that allows you to choose the protocol and fill in the details:
- choose ssh - set the repository path to: /cvsroot/robotcub - set your username - your password (unsecure) - the hostname: cvs.robotcub.org
and leave the other fields blank. When done, click ok and you'll get the CVSROOT field automatically filled for you. On the 'Globals' pane you might want to set the 'Prune empty directory' flag which corresponds to the -P option. Note that the CVS options from the command line are exactly the same you'll see in the little terminal on the bottom of the WinCVS main window.
Update: Right click on the folder name (containing your local copy) you want to update and check the 'create missing directories...' flag (corresponding to the -d). Click ok then to proceed with the updapte.
Commit: Right click on the folder name (left pane showing modules) to commit changes. Modified files are shown in red. Before committing you are asked to type the commit message (-m option). Click ok to proceed with the commit. Conflict are marked with a C and the file stays red. You should solve the conflict and commit again as before.
Add: Select the directory you wish to add on the right pane on the WinCVS main window and then press the little icon with the red cross in it (please note that the simple one is for adding ASCII files, the icon with the '01' in it is for binary files). Then repeat the select-add process for all the files you wish to add to the repository. Finally select the files or the parent directory and run a commit to complete the addition.
Tagging working versions of your code
One of the main advantages of using CVS is to be able to tag the current state of the code before major changes so that, if anything goes wrong, you can easily roll back to the latest working version.
In order to tag you code you have to declare a cvs module. This is done in the repository's module file which you can check out using the following command from your iCub directory:
cvs checkout CVSROOT/modules
This file contains a list of cvs modules. To declare you module you need to add a line giving the name of the module and what directory it contains. Below is the line I added for the arm_yarl module.
You have to commit the module file for the changes to take effect using commands such as:
cd iCub/CVSROOT cvs commit -m "Added the arm_yarl (yet another reaching learner) module" modules
With the new module declared, you can now tag the current version of the files using the commmand:
cvs tag SingleTarget-1-0 arm_yarl
Note that the tag name you choose, SingleTarget-1-0 in this case, cannot contains any dots (.).
This now allows you to work the magic revisions. Start adding to or modifying the code to your heart's content. If you ever come to think 'I wish I had that old working version back...' then your wish is CVS's command:
cvs checkout -r SingleTarget-1-0 arm_yarl
This will checkout the tagged files in the state they were when you gave them the tag.
Why not SVN?
Why not git? We're looking at our options.