A Mini Tour for CVS

Eric R. Bittner

Adopted from Haoxiang Luo's page for our group

This mini tour was intended for people in my group to get a quick start on CVS in case that they might be frustrated by the apparently long book (http://cvsbook.red-bean.com/cvsbook.html) which I actually strongly recommend to read.


Local CVS Info

In our group, the CVS server computer is eiger.chem.uh.edu and the CVS repository is in the /usr/local/cvsrep directory. You should use this as your main repository since it is periodically (weekly) backed up and archived.

What's CVS

CVS means Concurrent Version System.   It records the history of a group of files and coordinates between people who are working on a same project.

To record the history of your files, you could save every version of every file you have created. However, this is a clumsy way of doing that because it could waste an huge amount of disk space. CVS stores all the versions of one file in a single file in a much clever way. It only stores the differences between versions.

CVS also helps you if you are part of a group of people working on the same project. It's very possible that different people may work on a same file and make their own changes on it. CVS can be the coordinator for your group. CVS has a repository where it keeps all the files, from oldest version to newest. Each person in the project group can check out a copy of the files, and people work on their own copies. When some of them are done with their change, they may check in the files they modified so that other people can get the newest version. If more than one person made changes on the same file, then CVS can help resolve the conflicts.

Getting Help

  1. Simply type 'cvs' which gives you a brief overview of CVS.  Typing 'cvs help' gives you a list of common CVS commands and a brief description of each command.   Typing 'cvs -H [command]' or 'cvs --help [command]' provide you basic usage of the command.

  2. Read a very good online book at http://cvsbook.red-bean.com/cvsbook.html.

  3. Use man page of CVS (type 'man cvs').   Currently this is only available for Linux machines, not for the Mac OSX machines

  4. Go to the official site of CVS: http://www.cvshome.com.    The official manual by Per Cederqvist in several formats are available, known as "the Cederqvist".

CVS Setup

Set up CVS for your local machine:

If you want to create a CVS repository on your local machine, just make a repository directory, e.g., /usr/local/cvsrep.  Then you run

yourmachine:%cvs -d /usr/local/cvsrep init

to initialize the repository.     The command will create a subdirectory in the repository called CVSROOT which contains some administration files.

Setup CVS for Password-Authenticating Server:

You may let a remote CVS client to use the :pserver: method to connect to a repository.   The client connect to the server through the port number 2401.   In order to make this work, in addition to setting up the repository directory on the sever, you still have to do a few more things.

This is already in place on eiger.chem.uh.edu.

First, put a line like this into the file /etc/services:

cvspserver      2401/tcp

Then in /etc/inetd.conf, put this:

cvspserver stream tcp nowait root /usr/local/bin/cvs cvs  \
        --allow-root=/usr/local/newrepos pserver

Now users can log into the server by using their UNIX user accounts and passwords on the server.   However this is very undesirable since CVS does not encrypt the password when transfered over network.   You may disallow users to log in with their system passwords by editing the file server_repository/CVSROOT/config.   Just uncomment the line

# SystemAuth=no

or add it if it doesn't exist.

Then you specify the CVS client password by editing the file server_repository/CVSROOT/passwd and adding lines like these:


The first part of each line is the CVS user name, and the second part is encrypted password.   Same password can be used for everyone.  The password is encrypted using the same algorithm as the standard Unix system passwords stored in /etc/passwd.   You may acquire a encrypted password like that by changing your system password and then copy the encrypted text from /etc/passwd and paste to CVSROOT/passwd.   A better method is provided at http://cvsbook.red-bean.com/cvsbook.html#Starting_A_Repository.

The third part 'pubcvs' is a UNIX system account on the server that the CVS client is like when he/she accesses the repository.    You may set the UNIX level permission to the repository for this account so that the public can only have read access to your code, you may use similar method to give write-read permission to the group of people working on the project.

For the client who wants to access the repository on the remote server, (i.e hwaet.hpcc.uh.edu) he/she may login like this:

hwaet:% cvs -d :pserver:$USER@eiger.chem.uh.edu:/usr/local/cvsrep login

Or he/she may set the environmental variable:

hwaet:% setenv CVSROOT :pserver:$USER@turbulence.ucsd.edu:/usr/local/newrepository

where $USER is the CVS user name.   Then run

eiger:%cvs login

Once you log in, you don't have to do this again since CVS saved the information in the file .cvspass in your home directory.   You don't need login unless you change the password or you want to use another repository. Having just read this, forget it. It will not work since all of our machines use the SSH protocal. So, read on.

Use SSH for CVS connection

This is easier for the administrator because he/she doesn't have to do anything for the server once the repository is created.  The clients need to have UNIX accounts on the server machine and be able to connect to the sever using SSH.   To access the repository using SSH, do this first:

hwaet:%setenv CVSROOT :ext:$USER@eiger.chem.uh.edu:/usr/local/cvsrep
hwaet:%setenv CVS_RSH ssh

Then you don't need run 'cvs login', but run CVS commands directly.   The shell will ask for the password for your account automatically (typing password each time for this method could be annoying, I wrote a short article about how use SSH with password free which can find here). You should add these to your .cshrc file so you don't have to type it each and every time. Furthermore, you can bypass the password prompt by reading our group howto list.

Using CVS

Starting a new project

Suppose that we start a new project and the all the source codes are in the directory ~/cvs_test/. Assume that we already set the environmental variable CVSROOT (described in the previous part). First we go to that directory, and then run 'cvs import'.

eiger:%cd ~/cvs_test
eiger:~/cvs_test%cvs import projectname vendortag releasetag

where projectname is the name of the project, e.g., cvs_test. We don't have to worry about vendortag so far. Just use your first name. releasetag is a mark of moment for all the files. You may retrieve all files with status at this moment later. You may use an arbitrary string like start. After import, CVS will prompt an text editor to force you to add some comments about your action. This is a very useful CVS feature -- you have to explain why you made some change to the project (including start of the project). You may change the default editor by setting the environmental variable $CVSEDITOR. Now CVS repository has a module which is named projectname. You may simply go to CVS repository directory to take a look at the structure of the files if you have the access.

Checking Out A Working Copy

After you import a new project, the files in your current directory are still not under CVS control. To get a copy of code which is under CVS control, run command 'cvs checkout', or 'cvs co'

eiger:%cd ~
eiger:%rm -rf ~/cvs_test
eiger:%cvs co -d cvs_test projectname

Here I deleted the source from which I imported the project. -d cvs_test specifies the directory where you want to put the project. Here I call it again cvs_test. If you don't delete first, the directory will be simply overwritten.

Now if you go to the project directory (and each recursive subdirectory), you will see an extra directory called CVS. It saves some administration information about the current working copy, e.g., the corresponding repository.

Now you have a copy of the whole project of your own. You may edit each file as you want.

Committing changes

Run this

eiger:~/cvs_test%cvs commit [file names]

to check the file(s) you changed into the repository. If file name is missing, CVS check in all the changed files by default. Again CVS will prompt a editor to force you add comments. After finishing the comments, simply save it and exit the editor.

Adding a File you created locally to the repository
eiger:~/cvs_test%cvs add [file names]
eiger:~/cvs_test%cvs commit
Removing a File

To remove a file from the repository, delete it first from the local directory.

eiger:~/cvs_test%rm [file names]
eiger:~/cvs_test%cvs remove [file names]
eiger:~/cvs_test%cvs commit
Browsing Log Messages (finding out who did what)
eiger:~/cvs_test%cvs log [file names]

If file name is missing, CVS will show the log of all the files.

Checking file status

To see if a file is the newest version compare to the file in the repository, run 'cvs status'. For example, check file testfile:

eiger:~/cvs_test%cvs status testfile
File: testfile          Status: Up-to-date

   Working revision:    1.8     Wed Oct 24 17:03:49 2001
   Repository revision: 1.8     /usr/local/cvsrep/cvs_test/testfile,v

This means that testfile you have is up-to-date. It is same as the newest version in the repository, both having revision number 1.8. After you make some changes to testfile, then run this again:

eiger:~/cvs_test%cvs status testfile
File: testfile          Status: Locally Modified

   Working revision:    1.8     Wed Oct 24 17:03:49 2001
   Repository revision: 1.8     /usr/local/cvsrep/cvs_test/testfile,v

This means you modified the file locally, and nobody else has checked in a new version of the file. Now you may run 'cvs commit testfile' to check it into the repository.

If somebody else checked in a new version of testfile to the repository, you will see something like this (assume that you didn't do any change to this file):

eiger:~/cvs_test%cvs status testfile
File: testfile          Status: Needs Patch

   Working revision:    1.8     Wed Oct 24 17:03:49 2001
   Repository revision: 1.9    /usr/local/cvsrep/cvs_test/testfile,v

It means that the file in the repository is newer than what you have now. You may run 'cvs update', or 'cvs up', to update this file.

If you did changes to testfile and somebody also checked in a new version of it, then you will see this:

eiger:~/cvs_test%cvs status testfile
File: testfile          Status: Needs Merge

   Working revision:    1.8     Wed Oct 24 17:03:49 2001
   Repository revision: 1.9     /usr/local/cvsrep/cvs_test/testfile,v

which means you need to merge the changes in the repository and the changes that you've made. Now if you try to check in testfile, CVS will find that conflicts happened and show that an error occurred. You will have to run 'cvs update' to fix the conflicts first.

Finding differences between two revisions

Using 'cvs status', you can know if your file is same as the newest version in the repository (actually, you can compare any two old versions. Check the websites provided at the beginning for more information). To find out what the difference is if there exists any, use 'cvs diff'

eiger:~/cvs_tes%cvs diff [file names]

You will see this is same as using 'diff' command in UNIX to compare to files.

Updating files and Resolving Conflicts
eiger:~/cvs_tes%cvs up [file names]       # or cvs update [file names]

This can update your file(s) easily if you didn't change anything to them. If you did some change, conflicts may occur when you run ''cvs update'. CVS tries to merge the two versions and show you what the difference is in the file. You may have to open the file and edit it manually to resolve the conflicts.

Comments are welcome.

Mac CVS Client
Mac CVS Client is a FREE multithreaded cvs frontend for Mac OSX. You can download the latest version from here
Original version: Haoxiang Luo
Oct 23rd, 2001
Modified by Eric R. Bittner bittner@uh.edu Feb 9 2005.