How to use CVS

• General Description of CVS
• Some common CVS terminology
• Walkthrough of CVS
• Accessing CVS remotely
• More information

1. General Description of CVS

1.1 What exactly is CVS?

"CVS" is an acronym for the "Concurrent Versions System." CVS is a "Source Control" or "Revision Control" tool designed to keep track of source changes made by groups of developers working on the same files, allowing them to stay in sync with each other as each individual chooses.

1.2 Why is this useful?

CVS is useful for multiple developers working on the same files. The major advantage of using CVS over the simpler tools like RCS is that it allows multiple developers to work on the same sources at the same time. The shared Repository provides a rendezvous for committed sources that allows developers a fair amount of flexibility in how often to publish changes or include work committed by others.

1.3 How does CVS work?

CVS saves its version-control information in RCS files stored in a directory hierarchy, called the Repository, which is separate from the user's working directory. CVS uses the Repository to store the localized information. The files are worked upon in an individual user's directory and then imported to the Repository when the changes are committed. Files within the Repository are stored int a format dictated by RCS. CVS uses RCS to do much of its real work.

1.4 How does CVS differ from RCS?

CVS actually uses RCS to change the underlying RCS files in the Repository. RCS comprises a set of programs designed to keep track of changes to individual files. CVS coordinates interaction among groups of files. CVS automatically determines the state of a file (e.g. modified, up-to-date with the Repository, already tagged with the same string, etc.).

back to the top

2. CVS terminology

2.1 What is the "Repository"?

The Repository is a directory tree containing the CVS administrative files and all the RCS files that constitute "imported" or "committed" work. The Repository is kept in a shared area, separate from the working areas of all developers.

2.2 What is a working directory (or working area)?

A working directory is the place where you work and the place from which you "commit" files. The "checkout" command creates a tree of working directories, filling them with working files. Each working directory contains a sub-directory named ./CVS containing administrative files, which are created by "checkout" and are always present.

2.3 What is "checking out"?

"Checking out" is the act of using the "checkout" command to copy a particular revision from a set of RCS files into your working area. You normally execute "checkout" only once per working directory (or tree of working directories), maintaining them thereafter with the "update" command.

2.4 What is a module?

In essence, a module is a name you hand to the "checkout" command to retrieve one or more files to work on. It is a relative path to a directory or file in the Repository.

back to the top

3. CVS Walkthrough

3.1 How do I create a Repository?

Set an environment variable:
% setenv CVSROOT <dirname>

Or else this will happen:
% cvs checkout foo
cvs checkout: No CVSROOT specified! Please use the '-d' option
cvs [checkout aborted]: or set the CVSROOT environment variable.

<dirname> should be an empty directory (it need not even exist yet). Then tell CVS to initialize a repository there:
% cvs init

It is not absolutely necessary to initialize the repository before you begin using it, but skipping this step now will be difficult to fix later. Initializing the repository sets up several administrative and control files that are useful with some of the more advanced CVS commands. You'll be glad you did later.

Note: For info on remote access click here.

3.2 How do I begin a project?

Initialize a new module in the repository -- From the new project directory type:
% cvs import -m "Message" <module> <Vend-Tag> <Release-Tag>

How to start using the new module -- Tell the system that you wish to use an already initialized module:
% cvs checkout <module>

Now the directory <module> is opened to modify the files as a normal user directory.

3.3 How can I add files?

Adding a file -- First create the new file. Then use the add command to tell CVS what you want done:
% cvs add <filename>

Commit your final changes:
% cvs commit

3.4 How can I delete files?

Removing a file -- First delete the file. Then tell CVS that you wish to remove the file:
% cvs rm

Now commit your final changes:
% cvs commit

3.5 How do I make changes to existing files?

Modify the files as you would normally. Then use the update command to update the current files:
% cvs update
This checks version conflicts and marks the newer files for a final commit.

When you are sure of you changes, again, commit them:
% cvs commit
Committing will place your modified files into the Repository.

3.6 What if I want to revert to an older version of a file?

If you make unwanted changes to the version in your working directory, delete the file and use CVS update to retrieve the most recent versions from the Repository.

3.7 What if I want to specify an older version of a file?

• By tag or symbolic name, via the "-r" option
• By date, via the "-D" option
• By branch tag (a type of tag with a magic format), via the "-r" option
• By date within a branch, via the "-r :" option
• By an explicit branch revision number ("-r"), which refers to the latest revision on the branch
• An explicit revision number: "-r"

3.8 How do I find the differences between versions?

Use the CVS diff command:

% cvs diff

In the current directory, no arguments reports the differences from the files in the repository.

To find specific version differences:

% cvs diff -c -r 1.6 -r 1.7 <filename>

• "-c" is a more human readable format
• "-r 1.6 -r 1.7" displays the changes between version 1.6 and 1.7

3.9a How do I resolve conflicts?

If you have a conflict you will get the message:

cvs update: Updating .
RCS file: /<conflictfile>,v
retrieving revision 1.1
retrieving revision 1.2
Merging differences between 1.1 and 1.2 into <conflictfile>
rcsmerge: warning: conflicts during merge
cvs update: conflicts found in main.cc
C main.cc

3.9b What did it do to my file?

The file now has version information within it, for example:

<<<<<<< main.cc
  printf("Hello World\n");
=======
  printf("Goodbye World\n");
>>>>>>> 1.2

The pieces between the <'s and >'s are the conflicting pieces of code. You must decide which piece is correct.

3.9c How do I get CVS to accept the revision?

Modify the file in question to the appropriate modification, then commit the changes using the cvs commit command.

3.10 How do I rename a file?

CVS does not offer a way to rename a file so that it is still able to track the file later, yet you can use RCS to accomplish this task at a lower level. Copy the RCS (",v") file directly into the Repository:

cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v

Remove the old file using CVS:

% cd <working-dir>/<odir>
% rm <ofile>
% cvs remove <ofile>
% cvs commit <ofile>

Retrive <nfile> and remove all the Tags from it. By stripping off all the old Tags, "checkout -r" and "update -r" won't retrieve revisions Tagged before the renaming.

% cd <working-dir>/<ndir>
% cvs update <nfile>
% cvs log <nfile>
% cvs tag -d <tag1> <nfile>
% cvs tag -d <tag2> <nfile>

3.11 Cleanup - How do I get rid of the directory that "checkout" created?

Change your directory to be the same as when you executed the "checkout" command. If you want to get rid of the CVS control information, but leave the files and directories then run:

% cvs release <modulename>

If you want to obliterate the entire directory:

% cvs release -d <modulename>

back to the top

4. CVS Remotely

4.1 How do I access remote repositories?

If you are running on Unix, linux, or some variant that runs ssh, follow these directions (if you are running Windows see below). When you set your environment variables use these values:

   export CVSROOT=:ext:<username>@machine:<cvs directory> export
   export CVS_RSH=ssh

CVSROOT tells cvs where to look for the repository. username is a valid account that you can log into on machine. CVS directory is the path to the cvs directory. Keep in mind that CVS might expand ~ in weird ways so full path name is probably best.

Once you have these environment vars set execute cvs like normal on the machine where you will be working. When you try to access the repository you will have to type your password and everything should behave normally.

4.1 What if I want to do this from Windows?

It won't work. The problem is that Windows in general is way behind Unix from a security standpoint. Windows still works in a world of clear text passwords (aka telnet and rsh) while most security minded Unix machines use ssh. On turing we have disabled all unencrypted access which is what WinCVS (the Windows version of cvs) likes to use.

As of November 2000 there are long and detailed instructions on the WinCVS web-site (www.wincvs.org) that tell one how to get WinCVS communicating with a Unix based remote repository. I found that I couldn't get this to work. If you have better luck you might email staffnow and tell them how you did it so that they can update this document.

back to the top

5. More information

Quick CVS overview:
http://www.cvshome.org

In-depth FAQ documentation:
http://www.cs.utah.edu/dept/old/texinfo/cvs/FAQ.txt

CVS How-to on linuxdoc.org:
http://www.linuxdoc.org/HOWTO/CVS-RCS-HOWTO.html

back to the top

Copyright (c) HMC Computer Science Department. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License.''