What is CVS?

CVS is a version control system. A version control system maintains an organized set of all the versions of files that are made over time. Version control systems allow people to go back to previous revisions of individual files, and to compare any two revisions to view the changes between them. In this way, version control keeps a historically accurate and retrievable log of a file's revisions.

More importantly, version control systems help several people (even in geographically disparate locations) work together on a development project over the Internet or private network by merging their changes into the same source repository. It ensures that two people cannot inadvertently edit the same file at the same time and interfere with each other.

What is CVS for?

CVS maintains a history of a source tree, in terms of a series of changes. It stamps each change with the time it was made and the user name of the person who made it. Usually, the person provides a bit of text describing why they made the change as well. Given that information, CVS can help developers answer questions like:

Who made a given change?
When did they make it?
Why did they make it?
What other changes did they make at the same time?

CVS allows you to work within your own development cycle while keeping track of the project's overall development cycle.

You begin working on a project by obtaining your own working copy of files or modules (individual groups of project source files). The process is known as checking out the project repository.

You make your contribution to the project by modifying these files and creating new ones.

This part of the cycle doesn't involve CVS directly. You modify your working copies of project files using a file editor on your local machine. You can save your edited files to test how your changes affect the particular project module you are working in without affecting anyone else's work on those same project files. Nothing you do affects other project participants until you merge your changes into the project repository.

You test and tweak your latest changes in your own workspace to make sure these work without breaking or corrupting the overall project.

Finally, you contribute back or check in your changes to the main body of project files, merging your work with the most recent working version.

Committing your changes to merge with other developers' work is the most powerful aspect of CVS, but that power also makes it the most critical aspect. It's possible to get confused and accidentally overwrite someone else's changes. Understanding how and when to update your working copies and how to resolve merge conflicts are two particularly critical aspects of using CVS in collaborative development projects.
This copy-modify-merge cycle is repeated throughout the life of the project by all contributing developers. CVS enables everyone to work on project files simultaneously, to stay up to date on the latest changes contributed by others, and to test how their own changes affect the overall project without interrupting other developers' cycles.

The repository

The master copy of the files managed by CVS is called the Repository, and for the FreeBMD project this is on the development machine.

In order to use cvs you have to interact with the development machine using a secure protocol. This protocol is normally called SSh (Secure Shell), although strictly, SSh is a command line shell that uses the secure protocol.

Normally, you never access any of the files in the repository directly. Instead, you use CVS commands to get your own copy of the files into a working directory, and then work on that copy. When you've finished a set of changes, you check (or commit) them back into the repository. The repository then contains the changes which you have made, as well as recording exactly what you changed, when you changed it, and other such information.

Checking out a working directory

CVS doesn't work on ordinary directory trees; you need to work within a directory that CVS creates for you. You use the cvs checkout command to get a directory tree from CVS before working on it. The command for checking out the FreeBMD project files is: cvs -d yourname@test.freebmd.org.uk:/home/cvs checkout UKGEN-FreeBMD.

Making changes to files

Once CVS has created a working directory tree, you can edit, compile and test the files it contains in the usual way - they're just files.

Merging your changes

Since each developer uses their own working directory, the changes you make to your working directory aren't automatically visible to the other developers on your team. CVS doesn't publish your changes until you're ready. When you've finished testing your changes, you must commit them to the repository to make them available to the rest of the group.

However, what if another developer has changed the same files you have, or the same lines? Whose changes should prevail? It's generally impossible to answer this question automatically; CVS certainly isn't competent to make that judgement.

Thus, before you can commit your changes, CVS requires your sources to be synchronised with any changes committed by the other team members. You can achieve this by using the cvs update command.

Committing your changes

Now that you have brought your sources up to date with the rest of the group and tested them, you are ready to commit your changes to the repository and make them visible to the rest of the group. You commit them like so: cvs commit

Two Different Modes

There are two ways you can use CVS - which one you use depends on the kind of changes you will be making.

Independent Mode

Changes are made by a single developer working alone - this is the method used for source and web page changes.

Co-operative Mode

A file is normally only edited by one person at a time, or multiple editors will co-operate on the changes - this is the method used for district map changes.

Parts of this guide were taken from an article by Jim Blandy called Introduction to CVS
and from A Version Control Glossary

FreeBMD Main Page

© 1998-2008 The Trustees of FreeBMD (Ben Laurie, Graham Hart, Camilla von Massenbach and David Mayall), a charity registered in England and Wales, Number 1096940. We make no warranty whatsoever as to the accuracy and completeness of the FreeBMD data. Use of the FreeBMD website is conditional upon acceptance of the Terms and Conditions