CVS: An Introduction

Take advantage of the ability to track file versions, collaborate on projects and get back yesterday's work.
Using CVS

The basic steps for using CVS are as follows: check a project out of the repository, make changes to project files and verify whether they work, commit the modified files back into the repository and supply notes on the changes you made.

You have to check out files from CVS before you can edit them. By default CVS checks out the latest revision of a project, but you can specify earlier revisions if you wish. When you check out a project from the repository, CVS copies the project's files to the current directory, creating subdirectories as necessary. You can check out project files by specifying a directory name (e.g., html_projects) or by specifying a specific project file (e.g., html_projects/client1/index.html). Specifying a file still creates the project's directory structure in your working directory, but only the specified file is copied from the repository.

To check out client1's files, move to a directory where you can work, such as your home directory, and then issue the CVS checkout command shown below. You can easily end up with several copies of a project scattered about if you don't switch to the same starting directory each time you run the checkout command.

cvs checkout html_projects/client1

Next, switch to the client1 directory (cd ~/html_projects/client1) and make changes to the files using your favorite editing tool. Make sure your changes work before committing a file back into the repository. A common mistake when using version control software is to check in files too soon. This causes the repository to contain many versions of the file, most of which don't work.

To put the changed file into the repository, use the following command:

cvs commit -m "made some changes" index.html

CVS will let you know if the file was successfully placed in the repository and what its new revision number is.

You can retrieve earlier revisions of a file by specifying a revision number or a date with the checkout command. For example, if index.html is currently at revision 1.3 and you want to retrieve yesterday's version, which was 1.2, you can do so with either of the following commands:

cvs checkout -r 1.2 html_projects/client1/index.html


cvs checkout -D yesterday html_projects/client1/index.html
The -r switch allows you to specify a revision number, while the -D switch allows you to specify a date. You can specify an ISO standard date such as 2000-03-23 or a relative date such as “yesterday”.

Adding and Removing Project Files

To add a file to an existing project, check out the project then create the new file in the project's working directory. Add it to the repository using the following commands:

cvs add newfile
cvs commit -m "Added newfile to the project" newfile

Removing files is very similar to adding them. First check out the project, and then delete the files you wish to remove from the working directory. Remove them from the repository with:

cvs remove newfile
cvs commit -m "Removed newfile from project" newfile

Project Aliases

One way to deal with a repository full of project directories is to take advantage of the ability to use aliases in place of directory names in CVS commands. Aliases allow you to use short, meaningful names for projects instead of long directory names. An alias can also be used to group separate projects under a single name so they can all be checked out with one command. Finally, an alias can list specific project files, such as documentation or header files, allowing you to check out small pieces of a project. To use aliases you must edit the modules file in the CVSROOT directory of the repository. This is explained in the CVS documentation.

Tagging Project Files

CVS allows you to supply a symbolic or logical name (e.g., release-1 or beta) to all the files in a project with the tag command. Since each file in a project might have a different revision number, a tag provides a way to take a snapshot of the project at a given moment. You can then use the tag with the -r switch when checking out a project to retrieve that snapshot, without having to remember the version numbers of each file in the project. One thing to note is that tags can't contain spaces or periods.

Project Branches

CVS allows you to create branches of a project where each branch contains project code in different states, such as a bug-fix branch and a new features branch. You can work on different branches without affecting the other branches and then you can merge the changes from one branch into another automatically.

For the sake of example, let's assume you're working on a project called FaxMan and have released version 1.0. You tagged the source files in the repository as rel-1-0 upon release, then started working on version 2.0. Then you get complaints of bugs in version 1.0 that have to be fixed. To create a branch of the FaxMan project containing version 1.0 you can use:

cvs rtag -b -r rel-1-0 rel-1-0-bugfix FaxMan

The rtag command assigns a new tag (rel-1-0-bugfix) to the code in the repository. The -b flag means the tag is a new branch, and -r rel-1-0 means this branch contains the code previously tagged as rel-1-0.

To check out and work on the version 1.0 code you would use the following command:

cvs checkout -r rel-1-0-bugfix FaxMan

To merge the bug fixes with the current FaxMan code you first check out the latest code and then tell CVS to merge the rel-1-0-bugfix code with it. This is done using:

cvs checkout FaxMan
cvs update -j rel-1-0-bugfix