| Version 2 (modified by walt, 2 years ago) |
|---|
CVS tutorial
CVS is a network aware version control system. Several of the larger projects in the PARL lab use CVS to manage source code. These are some of the basic capabilities that it provides:
- automatically tracks changes to code so that old versions are backed up
- allows you to document incremental changes and browse this documentation
- multiple users can make changes simultaneously
- keeps multiple copies synchronized between different users
- allows you to work remotely
You can find out more information about CVS at http://www.cvshome.org.
Overview
CVS stores revision history for each file in your project. Each time you "commit" a file to CVS, a snapshot of its state at that time is stored in CVS. This allows you to back up to old versions at any time, or browse old versions to see how the code evolved. It is important to note that CVS stores version information independently for each file. There is no global verion number associated with your project at any time unless you manually assign it (see the "tag" feature, which is beyond the scope of this document). Version numbers for each file revision are assigned automatically by CVS; there is no way to control this numbering.
If you wish to assign a version number or logical name to the state of the entire project at one time (for example, release version 1.0), then you must do this manually.
Basic user commands
Before using CVS, you must set an environment variable that tells it where to look for the CVS repositories. If you are using tcsh, you can do something like this (and add it to your .cshrc file):
setenv CVSROOT /projects/cvsroot
and for bash:
set CVSROOT=/projects/cvsroot
Hmm. Should we maybe have a sample project in cvs that anyone can check out? Might be nice to be able to play with this stuff without hurting a real project
- export: If you wish to get a copy of a source tree with no intention of modifying it or manipulating it with CVS, you can just export it. This command creates a directory for the project and populates it with the source code. To export the most recent copy of a project:
cvs export -D today <projectname>
(where <projectname> is the name of the project). When you are done with the code you can simply delete the directory.
- check out: The check out command is used to obtain a copy of the source code that will be tracked by CVS. This will let you make changes and additions to the project. You must have appropriate permissions in order to perform this operation:
cvs co <projectname>
This will create a directory for the project that contains source code and CVS information. See the "commit" command for information on submitting modifications, and the "release" command to get rid of the directory when you are done.
The checkout command can be run repeatedly without any harmful side effects. This is useful for updating your copy of a project to make sure that it matches the most recent modifications before adding any modifications of your own.
- release: When you are done with a project, you may release the directory. This will warn you if you have made any modifications to the source code that have not been committed to CVS. The options listed below will also cause your copy of the project directory to be deleted. Note that it is perfectly fine to leave code checked out for long periods of time if you are going to be working on it regularly.
cvs release -d <projectname>
- commit: Once you have made any changes to the project, you must perform a commit operation to record the changes in CVS and make them available to other users. It is usually advisable to only commit code that compiles and works correctly, unless you are the only person working on the project. Otherwise, you may interfere with someone else's work. This command should be carried out within the project directory:
cvs commit
When you do this, CVS will open up a vi session that allows you to write a brief summary of the changes that you have made. Note that this summary will be associated with all of the files that you have changed since the last checkin, not just one. The commit will complete when you close the vi session.
- add: The add command is used to add new files to the project. You must create the new file first. Then run the following command from within the project directory that contains the new file:
cvs add <newfilename>
You must follow this up with a "commit" in order for other users to see the new file. This command may also be used to add new directories to a project. Add directories with caution, however. Unlike files, subdirectories are very difficult to remove from a CVS project.
- update: You will often find it necessary to update your copy of the project to reflect the most recent changes. Rather than use the update command, however, it is often better to simply run the checkout command again. It will detect if your project is already checked out and will update if needed.
- status: The status command will tell you the status of all of the files within a particular project directory. This is useful for determining if your copy is up to date or if it has been modified but not checked in:
cvs status
If you wish to filter the output from this command so that it only shows you files that are not up to date you may do the following (you can make this an alias or script if you wish to use this regularly):
cvs status |& grep Status: | grep -v Up-to-date
There are many other CVS commands and features, but the ones listed above should be enough to get you started. You can find out more information in the CVS man pages or by reading documentation at http://www.cvshome.org.
Starting a new project
Lab users can also create new CVS directories to keep up with software projects. These can later be merged in as part of another project if desired. To create a new CVS entry, go into the source directory and delete all of the binary or object files (assuming that you only wish to track the source code). Then run this command:
cvs import -m "Imported sources" <projectname> PARL start
(for the sake of clarity, <projectname> should probably match the name of the directory that contains the source)
Remote access
You can also access the PARL CVS repository remotely (outside of the lab) if you have an internet connection and the CVS and ssh programs installed on your remote machine. It works exactly like using CVS locally. You can use the same commands listed above, except substitute the following for the the word "cvs" in the command lines:
cvs -d :ext:<userid>@cvs.parl.clemson.edu:/projects/cvsroot
(where userid is your lab user login id) You may wish to create an alias or script to do this for convenience. CVS will prompt you for a password in this situation.
