CVS Basics (written for the dna group by Joseph Schaeffer) 1) The first thing you need to do in order to use the CVS system is to make sure the CVSROOT environment variable is set to the right location. Under tcsh, the command is: > setenv CVSROOT /research/CVS Under bash, the command is: > export CVSROOT=/research/CVS You should be able to execute "echo $CVSROOT" and get back the appropriate directory at this point. You may also wish to add this to your starting shell, this can be done by adding the appropriate line from above to .tcshrc or .bashrc, depending on shell. If you have questions about that part, please ask. Note: for remote CVS updates (from a computer not in the cluster), > setenv CVSROOT dna.caltech.edu:/research/CVS/ > setenv CVS_RSH ssh This can be handy for keeping laptop directories in sync with the cluster. 2) Setting up your own project directory in the repository. The first thing you should do is to organize the sources you want to be included in the project. This means that you should take all the source code, the Makefile, any readme documentation and other things necessary to the project and place them all in one directory or directory structure. If you are placing external source code (For example, the ViennaRNA-1.4 package source) in the repository, you should do the following: take the original .tar.gz file (or equivalent) and unpack it to a completely new directory. Do not run any makes, do not modify any files. At this point it is ready to be entered into the repository. If you have changes you need to make to it, wait until you have entered the source for the first time before making changes. This will ensure that the starting source in the repository is the same as the package source, making it easy for your changes to be applied to someone else's copies of the code (at another college, the creators of the program if you are fixing bugs, etc). The last thing you need to do is ensure that the entire group can read the source, which means that you will probably have to change permissions on the files you are going to import. The easiest way to do this is using the chmod command when you are in the project directory, like this: > chmod g+rw -R * This command adds group read and write permissions to everything in the current directory and all subdirectories. You are now all set to enter this project into the repository. To do this you type the following, while in the directory you want to be entered in the repository. For example, if I have sources in /home/schaeffer/ViennaRNA-1.4 which I want to be entered, I would first "cd /home/schaeffer/ViennaRNA-1.4". When entering the source into the repository, you have to give it several parameters. These are the name of the project (when in the repository), the initial message on the source code, and a vendor tag and release tag. The vendor tag and release tag are meant for industrial-type releases, and we will fill those with default data. Here is the actual import command: > cvs import -m "[message here]" [project name] [vendor tag] [release tag] So, for my previous example, I would do this: > cvs import -m "ViennaRNA-1.4 imported code, from ViennaRNA-1.4.tar.gz at http://www.tbi.univie.ac.at/~ivo/RNA/index.html" ViennaRNA-1.4 vtag rtag Note that I have put a reference to the source of the imported code in the message, so that it is clear where the code can be retrieved from. The project will be entered into the repository as ViennaRNA-1.4 and I have filled the vendor tag and release tag with dummy information. 3) How do you actually use the repository? There are five main commands with you will need to know, so we will go through these in order. -------------------------------- --- checking out source code --- -------------------------------- This is done with the checkout command. If you want to grab a copy of the source code to work with, all you need to do is run the checkout command and give it the name of the project which you would like to retreive: > cvs checkout [project name] To continue our previous example, this command: > cvs checkout ViennaRNA-1.4 Would check out the project ViennaRNA-1.4. It will create a new directory off the current directory with the name ViennaRNA-1.4 and retrieve the project into that directory. Note that it always creates a new directory from the current directory. -------------------------------------------------- --- updating the local copy of the source code --- -------------------------------------------------- Say that someone else has made a change to the source code in the repository and you wish to retrieve that change. The command you would want to use is update: > cvs update This should be run from the source directory which you want to retreive updates for. For example, if I wanted to check the ViennaRNA-1.4 source for new updates in the repository, I would first change to the directory created for the project by the checkout command, (ie cd ViennaRNA-1.4) and then run cvs update. This will retreive any new or updated files from the repository. There is another good use for this command, which arises from the status display it gives for each file it finds. When processing the files, it gives one character to indicate the status of each file (out of "UARMC?"). These are: U: The file was brought up to date from a newer version in the repository. A: This file is scheduled for addition to the repository. R: This file is scheduled for removal from the repository M: This file was modified from the repository version and is either unchanged or was merged successfully with any repository changes. C: A conflict was found when updating this file and it could not be merged. In this case you will need to merge the files by hand. ?: File is not in the repository, but exists in the working directory. This display is useful if you need to check which files you've newly created but not added the the repository and so on. ---------------------------------------- --- adding a new file to CVS control --- ---------------------------------------- Say you have created a new source code file for a given project (after it was first imported) and want to add it under cvs. The command for this is: > cvs add [filename] This tells CVS that the next time you commit changes to the repository, it should also add the given file to the cvs repository as a new file. ----------------------------------------------- --- remove a file from being cvs controlled --- ----------------------------------------------- This should only be used if you are working on a personal project and a file is no longer necessary to the project. For example, say I had a header file "bleck.h" which is no longer referenced by any of the source code in my project. I should then remove it from being in CVS as it is no longer needed. The command for this is: > cvs remove [filename] This tells CVS that the next time changes are committed to the repository, it should remove the given file from being controlled by the cvs repository. -------------------------------------------- --- committing changes to the repository --- -------------------------------------------- Note that changes are considered to be any modification of a file which is stored in the repository, and also cvs add and remove file commands. So if you were to use cvs add to add the file grep.c to your current module in the repository, it will not actually make that addition until you run a commit operation. This is done with the CVS commit command, like so: > cvs commit This command should be executed from directory which you would like to submit changes for. Continuing our previous example, if I wanted to submit my new changes to the ViennaRNA package, I would change to that directory (which had previously been checked out and then modified) and run cvs commit. It will then check for any files which you have changed and attempt to resolve those into the respository. If for some reason there is a conflict, it will immediately stop the attempt to commit the changes and notify you of a conflict between your version and the existing version (I.E. if your version was based off of 1.1, and someone else submitted changes, bringing it to 1.2, if you then ran commit it would ask you to merge your changes with those between the existing 1.1 and 1.2). If it does this it will create a file for you to edit which will contain all the differences between your file and the newly changed one from the repository. Edit this and run commit again to perform the merge. The other important thing when running commit is that it will ask you for a message describing the changes you made. It will also give a bunch of lines headed with "CVS:" which will not be entered into the change log, but are there to help you know what changed. This message is entered by way of vi, a text editor. For those who do not know how to use vi, here are the commands you will need to know: Type "i" to enter insert mode, at which point you can enter the text of your change message. When you are done, hit the ESC key. At this point, type ":wq" (which is the command to write the buffer and quit) and it will save your change message and then proceed with the commit process. If you don't like the vi editor, you can use another, e.g. > setenv CVSEDITOR /usr/bin/emacs to use emacs. Even easier, if your message is short, you can just include it on the command line and no editor will be called, e.g. > cvs commit -m "Added figure 5 and corrected the math error in calc.m" 4) Random Information Things to remember: Update your copies often. If you commit changes to the repository, they should be complete, so that anyone who retreives the current copy of the source code can compile a running program (though perhaps without the features you were adding). This is more of a rule for modifying already running source, like the ViennaRNA source code. If you are worked on your own individual project, this will not be as important as it is not expected to be running yet and it is better to commit changes every day or more often. Don't forget to commit changes! If you check out a copy and then don't commit your changes for a month, at best your version might be mergable with the one in the repository, if noone else made any changes, and at worst it will be completely useless as there will be an incredible number of changes. You should probably commit your changes at least every day. This also means that if something goes wrong you have more options to choose from when you need to go back to older source code. Don't add binaries to the repository - the repository doesn't need object files or the programs themselves, all it really needs is source, documentation and make files. It should be complete so that anyone can check out the source and compile the program, without having to rely on a binary that has been stored into CVS. If you have more questions, read the man page or check the help file - "man cvs" or "cvs --help". They are greatly helpful if you already have some familiarity with the program and/or have a specific thing you want to know how to do. I've only begun to touch upon the options available in cvs. If you have other questions, please feel free to ask me.