CSC 308 CVS Basics

CSC 308 CVS Basics

CVS is the "Concurrent Version System". It maintains a version repository that records the history of a project's files. Members of a project team each maintain an individual working directory. The working directory contains files that each member is in charge of plus copies of files that other members are in charge of.

There are two fundamental operations of any version control system:

file check in, from a individual working directory to the repository
file check out, from the repository to a working directory

In CVS, check in is accomplished using the cvs add and cvs commit commands. Check out is done most frequently with the cvs update command.

There are a variety of other useful CVS commands, including:

removing unnecessary files
checking file status
controlling which files are recorded in the repository
comparing past versions

Listed below are specific steps for setting up and maintaining a CVS repository. The steps cover initial creation of the repository, checking in, checking out, and other useful commands. There are a great many more CVS commands than those listed below. For CSC 308, these basics should be all you need. Further documentation on CVS is available online in the 308 documentation directory.

1. Defining the CVSROOT environment variable (one time only)

cd ~
emacs (or vi or pico) .cshrc
Go to the end of the file and add the following five lines:
#
# CVS settings
#
setenv CVSROOT ~librarian/projects/CVS
umask 022
Exit the editor
source .cshrc

2. Initial library setup, in the librarian's projects directory (one time only)

cd ~
mkdir projects
mkdir www
cd www
ln -s ../projects .
cd ../projects
mkdir CVS
mkdir work
mkdir alpha
cvs init
cd work
mkdir your-project
cd your-project
~gfisher/classes/308/admin/mkdirs.csh
cvs import -m "Initial creation" your-project csc308F06 start
cd ..
rm -rf your-project
cvs checkout your-project
cd ..
chmod -R a+rX .
chmod -R g+w .

3. Initial project checkout, from repository to individual team member directories (one time only)

cd ~
mkdir work
mkdir www
cd work
cvs checkout your-project
cd ~/www
ln -s ../work/your-project .
cp ~gfisher/www/.htaccess .
cd ~
chmod -R a+rX .

4. Check in new work, from individual team member directory to repository

cd ~/work/your-project/...
create some-file
cvs add some-file
cvs commit -m "log message" some-file

5. Check in revised work, from individual team member directory to repository

cd ~/work/your-project/...
edit some-file
cvs commit -m "log message" some-file

6. Check out other team members' work, from repository to individual directory

cd ~/work/your-project
cvs update -d

7. Release (by librarian) of team members work, from repository to projects/work directory

cd ~librarian/projects/work/your-project
cvs update -d

8. Removing previous checked in files

To remove a file X that is already in the repository, do the following:

cvs remove -f X
cvs commit -m "..."  X

The "-f" option to remove tells cvs to force the removal of the file; this will both remove the file from your working directory and schedule it for removal from the repository. The cvs commit, as with add, will actually commit the removal.

9. Viewing the status of individual work files compared to the repository

You can get a short form file status list as follows:

cd ~/work/your-project
cvs -n -q update

The `-n' option means to not actually do the update, but merely to display statuses; the `-q' option avoids printing the name of each directory. When you use cvs update in this way, you will receive a list of files in your work directory that differ from the repository. Each file will be preceded with a one-letter code, described as follows:

Code Meaning
U Another team member has checked in a changed version of the file. Use cvs update without the -n argument to update your version of the file from the repository.
M You have modified the file since the last time you checked it in. Use cvs commit to update the repository from your file.
? You have created a new file that is not yet in the repository. Use cvs add and cvs update to add your file to the repository.
A You have added a file (via cvs add) but not yet committed it. Use cvs commit to commit it to the repository.
R You have removed a file (via cvs remove) but not yet committed the removal. Use cvs commit to commit the removal from the repository.
C A conflict exists because someone checked in a file to the repository that you have modified. This case should never happen given the CSC 308 convention that only one person checks in a given file. If it does happen, see "Dealing with a Conflict" below.

You can get a long form file status listing as follows:

cvs status

This presents basically the same information as cvs -n update, in a more verbose format.

10. Viewing a Log Report

CVS maintains a complete log of all repository activity. To view the log for the project, do the following:

cd ~/work/your-project
cvs log

This will report a log for all project files, including when they were checked in, who checked them in, and the log message that was given at the time of check in. To view the log for a project subdirectory, go to that directory and run "cvs log". To view the log for a file X, provide the file name as an argument, i.e.,

cvs log X

11. Dealing with a Conflict

As noted above, a conflict means that someone else edited a file and checked it in at the same time you were editing the file as well. The best way to deal with conflicts is not to let them happen in the first place. That is, observe the rule that one person owns a file and only that person should edit that file. If someone needs to edit a file owned by someone else, the would-be editor should contact the owner and confirm that the editing can be performed and committed.

If a conflict does occur, the most straightforward way to deal with it is to move the conflicting file out of the way and run cvs update on the file. E.g., for a conflicting file X, do the following:

mv X X.sav
cvs update X

At this point you compare X with X.sav to see what differences there are and how to deal with the differences. If it turns out that the updated file X is the correct version, then simply delete X.sav. If on the other hand X.sav is the correct version, then delete X and commit X.sav. If both X and X.sav have valid information, then you must create the appropriate new version based on the desired contents of both files, delete the old version and commit the new one.

12. Telling cvs to ignore certain files, such as binary executables

Within the directory where the files to be ignored reside, add the names of the files to a .cvsignore file. Note that since .cvsignore is a regular file, it should be added to the repository just like all other files.

13. Fixing permissions after a file is checked in

Whenever a file is checked in, you must ensure that its permissions are world readable. The umask setting of 022 (from Step 1 above) automatically makes all newly created files world readable, so this will be the normal state of your files.

If a file is checked in without world-read permissions, you can go to the repository and change the permissions there. This is possible since cvs retains file ownership to be that of the user who last checked in the file. To change permissions for a checked-in file named X in projects subdirectory D, do the following:

cd ~librarian/projects/CVS/your-project/D
chmod go+r X

14. Removing ''sticky tags''

Occasionally, a CVS command you run may result in the attachment of a "sticky tag" to a file under CVS control. Sticky tags do have a useful purpose, but we don't care about them in 308. And the problem with a sticky tag is that it can prevent you from updating a file to a new version. To get rid of a sticky, use the "-A" argument to cvs update. E.g., to remove the sticky tag from a file X, do the following:

cvs update -A X

15. Permanently removing a directory

The removal procedure described above does not work for directories. CVS discourages directory removal, since it can disrupt the version history of files that were stored in the removed directories. So, directory removal from a CVS hierarchy must be done manually, by the following steps:

cd ~librarian/projects/CVS/your-project/...
rm -rf directory
cd ~team-member/work/your-project/...
rm -rf directory
edit CVS/Entries
delete the line in the Entries file containing the name of the deleted directory

The last two steps must be performed by each team member in the work directory. These two steps must also be performed by the librarian in the projects/work directory.

16. Connecting to a CVS server remotely

If you're running on a remote machine with CVS installed, you can connect to hornet as a CVS remote server by setting the environment variables CVS_RSH and CVSROOT as follows:

setenv CVS_RSH ssh
setenv CVSROOT :ext:user-id@hornet:full-librarian-path/projects/CVS

This is the UNIX-style method for setting environment variables. If you're running on a remote Windows client with CVS installed, use the "set ...=..." syntax for setting environment variables. After setting CVS_RSH and CVSROOT in this way, you can issue CVS commands as described in the steps above, as Windows text commands.

There are GUI-based CVS client programs available for use on Windows, Mac, and UNIX. A Java-based CVS client that runs on all platforms is jCVS, available at www.jcvs.org. WinCVS is a popular Windows CVS client, available at www.wincvs.org; the Macintosh version, MacCVS, is available at the same site. There is also Tortoise CVS, which is a client that runs under Internet Explorer, available at http://www.tortoisecvs.org.

Code	Meaning
U	Another team member has checked in a changed version of the file. Use `cvs update` without the -n argument to update your version of the file from the repository.
M	You have modified the file since the last time you checked it in. Use `cvs commit` to update the repository from your file.
?	You have created a new file that is not yet in the repository. Use `cvs add` and `cvs update` to add your file to the repository.
A	You have added a file (via `cvs add`) but not yet committed it. Use `cvs commit` to commit it to the repository.
R	You have removed a file (via cvs remove) but not yet committed the removal. Use `cvs commit` to commit the removal from the repository.
C	A conflict exists because someone checked in a file to the repository that you have modified. This case should never happen given the CSC 308 convention that only one person checks in a given file. If it does happen, see "Dealing with a Conflict" below.