Ask SIPB - September 24, 2004

This week, we continue our discussion of version control systems and explain CVS, the Concurrent Versioning System. If you're new to version control systems, refer to our May 11 column at http://www.mit.edu/~asksipb/ for an introduction.

How do I start using CVS and create a CVS repository?

Before you can do anything in CVS, you need to create a CVS repository. All of the files go into the CVS repository, and then when users want to edit them, they make their own local copies. This means that multiple users can edit a file at the same time, since they each have their own copy of it.

Once you decide where you want your repository to be, you should point the CVSROOT environment variable to the repository location. For example:

setenv CVSROOT /mit/asksipb/cvstest

After doing so, typing cvs init will set up an empty repository. (You can also use the -d option to specify a repository location instead of using CVSROOT, but CVSROOT is usually easier.)

Each CVS repository can have several projects. Now that your repository is ready, you can either import an existing directory structure or start from scratch.

To import an existing directory structure, cd to the directory, and type:

cvs import -m "imported directory" projectname vendortag releasetag

projectname controls where the project is stored in the repository. vendortag and releasetag aren't particularly important, but are still required. Your username for vendortag and start for releasetag would be reasonable defaults.

To start from scratch, create an empty project directory, and then follow the steps above.

How do I check out a project?

Before you can work with a project, you have to check it out. This is an area where there is a slight difference with RCS. In RCS, you check out files as you want to work on them. In CVS, however, you have to check an entire project to work with.

To check out a project, you use the cvs checkout command. As before, you either need to have CVSROOT defined, or use the -d option to specify the location of your repository.

cvs checkout projectname

After checking out a project, a subdirectory with the same name as the project you checked out will be made in your current working directory. It will contain all of the files in the project, and you can edit them at your leisure.

How do I check files back into the repository?

Once you are done editing your files, you may wish to check them back into CVS. To do so, use the cvs commit command, or cvs ci for short. For example:

cvs ci -m "Fixed a typo" intro.html

When you specify a filename, you check in that file specifically. If no file is specified, you are checking in all of the files of the project that you have modified. The -m flag allows you to add a message to your commit. If -m is not specified, CVS will invoke the editor pointed to in the CVSEDITOR environment variable, and ask you to type in a message.

If you are not using the most up to date version of the file, CVS will not check in the file. You will need to run cvs update as described below before reattempting the checkin.

How do I add a new file to the repository?

To add a new file to the repository, run:

cvs add filename

This marks the file as a new file to be added. It is, however, not immediately added to the repository. To actually add it, you will also need to run:

cvs commit

How do I update my local copy and see what changes have been made to the repository?

Suppose your friend has made changes to the project and you want to get a local copy of them for yourself so you can look over them or make more edits. To do this, you use the cvs update command, or cvs up for short.

You may want to consider using the -d option when you use cvs update. This will ensure all directories in the repository are also in your local copy, even if some directories were added to the repository after you initially checked it out. The -P option is also useful, as it will prune empty directories from your local copy. CVS does not provide a way to remove old directories, which is why this option can be necessary.

After a cvs update, you will have the most up-to-date copy of the files in the repository. If other people have made changes to the same file that you have been working on, their changes will be merged into your local copy. If these changes conflict, CVS will mark the differences with the lines "<<<<<<<", "=======" and ">>>>>>>". Look over the changes made, fix things as necessary, and remove the line markers.

What other CVS commands are available?

To take a look at the differences between your copy of a file and the repository's copy of a file, use the cvs diff command, with your filename as an argument. Without an argument, a diff will be performed on all of the modified files in your project. This is similar to rcsdiff in RCS.

Similarly, the cvs log command will show you what changes have been made to a particular file, like rlog does in RCS.

How can I use CVS with Emacs?

As with RCS, you can check in files in Emacs with the keystrokes C-x v v. When checking in a file, Emacs will open a buffer prompting you to enter a change comment. After entering your comment, C-c C-c will end your comment and check in the file.

Where can I find more information about CVS?

You can find the CVS web site at http://www.cvshome.org/, and the manual for CVS at http://www.gnu.org/software/cvs/manual/.

To ask us a question, send email to sipb@mit.edu. We'll try to answer you quickly, and we can address your question in our next column. You can also stop by our office in W20-557 or call us at x3-7788 if you need help. Copies of each column and pointers to additional information are posted on our website: http://www.mit.edu/~asksipb/