Carview!

Content preview·Buy reprint rights for this chapter

CVS is a version tracking system. It maintains records of files throughout their development, allows retrieval of any stored version of a file, and supports production of multiple versions. CVS enables multiple developers to work simultaneously on a single file without loss of data. Each developer works on her own copy of a file, and all changes are later merged into a single master copy. CVS can be integrated with bug-tracking and feature-tracking systems, and it provides features that can assist a project manager by tracking changes to a project over time.

CVS can be used in many environments for many purposes. It is used for maintaining configuration files, mail aliases, source code, FAQ files, art, music, articles, essays, and books. Some system administrators keep everything in the /etc directory under CVS in order to track system configuration changes over time. CVS is also used to store and automatically publish content to web sites and FTP servers.

CVS follows the Unix ethos of small programs doing what they do well. The RCS (Revision Control System) program handles revision control of single files, so CVS uses RCS to store file data. CVS adds features to RCS, most notably the abilities to work over collections of files, and to work out of a repository that may be local or remote.

Version control is the process of recording and retrieving changes in a project. A version control system can enable you to retrieve an old version to fix bugs or update features, branch development to allow the project to progress along multiple tracks simultaneously, and generate reports that show the changes between any two arbitrary stages of a project.

Most version control systems store notes with each change, and many provide tools that allow a project leader to analyze the changes. Most also include the ability to retrieve differences between arbitrary versions of files, which makes it easier to create patches or locate bugs.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Version control is the process of recording and retrieving changes in a project. A version control system can enable you to retrieve an old version to fix bugs or update features, branch development to allow the project to progress along multiple tracks simultaneously, and generate reports that show the changes between any two arbitrary stages of a project.

Most version control systems store notes with each change, and many provide tools that allow a project leader to analyze the changes. Most also include the ability to retrieve differences between arbitrary versions of files, which makes it easier to create patches or locate bugs.

The benefits of a version control system such as CVS include:

Any stored revision of a file can be retrieved to be viewed or changed.
The differences between any two revisions can be displayed.
Patches can be created automatically.
Multiple developers can work simultaneously on the same project or file without loss of data.
The project can be branched to allow simultaneous development along varied tracks. These branches can be merged back into the main line of development.
Distributed development is supported across large or small networks. (CVS offers a variety of authentication mechanisms.)

Using version control for a project requires some extra work on an ongoing basis. In addition, previous versions of files, or records of changes to the various files in a project, occupy disk space that you might otherwise use for something else. However, the features that a good version control system makes available are well worth the investment of time and disk space. For example, without version control, project backups typically are timestamped copies of an entire project, hopefully stored together in a logical fashion. Version control provides organized storage and retrieval of the complete record of project changes, rather than whichever copies someone gets a chance to make.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS records file changes during a project's development. Project files are added to the repository as they are created, and developers check out a personal sandbox — a personal copy of the project's files — to work from. Each developer works in her own sandbox and regularly commits her changes to the repository. Developers also update the contents of their sandboxes regularly to ensure that changes to the repository are reflected in each sandbox.

The term project can take on many different meanings. The stereotypical CVS project is a programming project in which files contain source code for the various programs written as part of the project. But that's a narrow view of what a CVS project can be. CVS can be used in many other settings as well, as the next few sections demonstrate.

CVS can store configuration files, mail aliases, domain records, and other files for which changes should be tracked. Import the files (or all of /etc) into a repository and require administrators to check them out into a sandbox to make changes. Commit the files back to the repository and export the changes to the server. If the changes fail, rolling back to the previous state is easy.

Multiple servers with varied but similar configurations can be maintained using different branches of the same files. Changes to any given branch can be merged into other branches selectively.

Every change made through CVS is recorded in a file history, along with the username of the person making the change, the date the change was made, and any notes recorded with the change. All this information can help, for example, when trying to spot which change to which configuration file broke the mail server.

Both the CVS server and the client run on all Unix and Linux operating systems. Third-party graphical clients are available for Unix, Linux, Windows, and Macintosh systems, and for the Java runtime environment. The CVSNT CVS server is available for Windows NT or later. This makes CVS particularly useful for cross-platform environments.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

To help you get up to speed quickly using CVS, this chapter explains the most common CVS operations. The commands and examples in this chapter are based on standard situations and cover only the most common options. Future chapters go further in depth on each topic covered in this chapter.

The examples and instructions in this chapter are based on the Unix/Linux command-line CVS client. Most graphical clients use the CVS command names for their menu options and buttons, so if you're using a graphical client you should be able to follow this chapter reasonably easily. Graphical clients and clients for operating systems other than Unix/Linux are described in Appendix A.

You may not need to read all of this chapter; follow these guidelines:

If you're working on an existing project that is already stored in CVS, skip the early sections and start at Section 2.5.
If CVS is already installed and running, with a repository available for your project, go straight to Section 2.3.

If you're not sure whether CVS is already installed and running, read the first part of Section 2.1; it tells you how to check. If you're uncertain about having a repository, try searching for the directory CVSROOT . The repository root is then the directory that CVSROOT is in. The other directories in the top level of the repository are CVS projects.

CVS is client/server software that runs on Unix and Linux platforms. When you install CVS on a Unix/Linux server, you automatically get both server and client software. To access CVS across the network from any Unix/Linux machine, simply install CVS on the machine in question. The server and client software are one and the same.

CVS is available from https://www.cvsgui.org. It is also available as an installation package from many GNU/Linux distributions, including Debian, Red Hat, and SuSE.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS is client/server software that runs on Unix and Linux platforms. When you install CVS on a Unix/Linux server, you automatically get both server and client software. To access CVS across the network from any Unix/Linux machine, simply install CVS on the machine in question. The server and client software are one and the same.

CVS is available from https://www.cvsgui.org. It is also available as an installation package from many GNU/Linux distributions, including Debian, Red Hat, and SuSE.

If you prefer GUI clients, I recommend a visit to https://www.wincvs.org. There you'll find gCVS, WinCVS, and MacCVS, which are GUI clients for Unix and GNU/Linux, Windows, and Macintosh (pre-OS X), respectively.

If you are a Macintosh user running OS X, you can install the standard Unix CVS server and client.

A Windows-compatible CVS server is available at https://www.cvsnt.org. This server is not identical with the Unix server, but the differences are clearly listed in the FAQ and an installation guide is available on the web site.

If you plan to use the Secure Shell (SSH) protocol to establish secure connections between CVS clients and CVS servers, you'll need to install compatible versions of SSH on your client and server machines. For clients, you may need to find a version of SSH that can be used from the command line. See Section 2.4 for more information on this topic.

The OpenSSH web site (https://www.openssh.com) is a good starting point for information on SSH and SSH clients. You may also want to read SSH, The Secure Shell: The Definitive Guide (O'Reilly) by Daniel J. Barrett, Ph.D. and Richard Silverman. For more than you ever wanted to know, check the SSH FAQ at https://www.employees.org/~satch/ssh/faq/. The Google list of SSH documentation is at https://directory.google.com/Top/Computers/Security/Products_and_Tools/Cryptography/SSH/Documentation/.

Most Unix and Linux systems have an SSH client installed as part of the standard set of programs. Mac OS X also has an SSH client preinstalled. If it is not installed automatically, an SSH client is usually available in your distribution as an optional program.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS relies on a file-based database called the CVS repository. The repository needs to be hosted on a machine with sufficient disk space to store your files and all the change data for your projects. The repository should be accessible to all the users from their workstations.

If the repository is on a remote computer, I recommend that users access the repository via SSH. Ensure that the server is running an SSH server and the workstations have a compatible SSH client. For more information on remote repositories and SSH, see Section 2.4 later in this chapter. Chapter 8 contains a full discussion of remote repositories.

For any one project, ensure there is enough disk space for three times the expected final size of that project. If you intend to store binary files, multiply by at least five. After your first project, you'll have a feel for how much space to allow.

A repository can store many projects. If you are creating a repository that may be required to handle several projects of unknown size, estimate what you can and ensure you can add more room later.

A CVS repository is user data, and it should be on a partition that is backed up and won't shut down the machine if it gets full. Repositories are often stored in /cvsroot, /var/lib/cvsroot, /home/cvsroot, or /usr/local/cvsroot. According to the Filesystem Heirarchy Standard (available at https://www.pathname.com/fhs/), the preferred location for a repository is /var/lib/cvsroot.

Another possibility is to put the repository in /cvsroot. This is easiest for users to remember.

Example 2-5 illustrates the steps involved in creating a repository. First, create the repository root directory on the CVS server. In Example 2-5, I create the /var/lib/cvsroot directory.

Example 2-5. Creating a repository

$ mkdir /var/lib/cvsroot
$ chgrp anthill /var/lib/cvsroot
$ ls -la /home

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

When you have created a new repository, you may want to import a project — a related collection of files stored under a single directory. It is possible to store a single file under CVS, but it will also be a project and you will need to store it under its own project directory. CVS needs to be able to create a subdirectory to store metadata about the project.

Before loading a project into CVS, consider the project's structure. If you move a file after it has been created and stored in CVS, CVS treats it as two files: the original in the original location and the new file in the new location. The history of the file is then split into two parts. Decide how you want to structure the source files for a project before you import it into CVS.

If you will eventually want to distribute your project's files across several unrelated directories, it is best to develop the project under a single root directory, then distribute the files as part of the installation script. Chapter 7 describes the issue of project structure in more detail.

If you have binary files or other files that are not plain text, please see the information on binary files in Chapter 3 before adding them to the repository.

Create your initial project directory structure, possibly in /tmp. Once the project is stored in CVS, this initial version can be removed. You won't be using it as a sandbox and the project is duplicated in CVS, so there's no reason to retain it.

Once you have your initial structure, add any initial files you want. Change into the root directory of the project. Then, from within that directory, import the project with the command:

cvs -d repository_path import name_of_project vendor_tag release_tag

If the repository is on the local machine, use the full path of the repository directory for the repository path. If the repository is on a remote server, see Section 2.4 for help on specifying the repository path.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

There are several ways to access a remote repository. This quickstart guide uses the ext method with the SSH protocol, but if your system administrator gives you different instructions, follow those. Chapter 8 explains the use of remote repositories in detail. The ext and SSH approach uses the ext repository access method, with an SSH client as the program that performs the connection. These are also explained in Chapter 8.

Your first step, at least the first step that I recommend, is to install SSH on the client machine. Make sure that the client-end SSH protocol matches the server's SSHprotocol. Set up SSH keys or passwords and test the connection. Using SSH enables you to create a secure connection to the remote repository.

Next, if you're on a Unix or Linux system, set the CVS_RSH environment variable on your client machine to the name of your SSH program, usually ssh or ssh2. Graphical clients that support the ext and SSH approach may have ssh as an authentication type option in the dialog that requests the repository path. Check the documentation for your client.

In WinCVS and gCVS, call up the Preferences dialog under the Admin menu and select "ssh" as the Authentication method under the General tab. In MacCVSX (for OS X), ssh is available under the MacCVSX menu. MacCVS for OS 9 and earlier versions do not support SSH as a standard option. Instead, you can make use of SSH from MacCVS via port tunnelling, as described in Appendix A.

If the repository is on the same machine as the client, the repository path is simply the full path to the repository's root directory. On a remote machine, the repository path takes the form:

[:method:][[[user][:password]@]hostname[:[port]]]/path

The method is the protocol used to connect to the repository. To use SSH, use ext as the method. Include the username and the @ if the username on the server differs from the username on the client. If you don't have an SSH key on the host, the system asks you for a password when you try to log in.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS stores projects and files in a central repository, but you work from a working copy, called a sandbox , in your local directories. You create that sandbox with cvs checkout .

CVS creates the sandbox as a subdirectory of your current working directory. I like to create a directory to contain all my CVS sandboxes, and I use ~/cvs. From whichever directory you want a sandbox created in, run the command:

cvs -d repository_path checkout project_name

This command checks out all files for the named project. If your repository is on the local machine, the repository path is the full pathname of the CVS repository. If your repository is on a remote server, see the earlier Section 2.4. Example 2-10 shows a local checkout.

Example 2-10. Local repository checkout

$ mkdir ~/cvs
$ cd ~/cvs
$ cvs -d /var/lib/cvsroot checkout example
cvs checkout: Updating example
U example/file1
U example/file2

The checkout command puts a copy of the project's files and subdirectories into a directory named for the project, created in the current working directory. It also puts some administrative files of its own in a subdirectory of the project directory, called CVS.

You can check out an individual file or subdirectory of a project by replacing project_name with the pathname to the file or directory, from the project's root directory. See Chapter 3 for more information.

CVS stores the repository path as part of the sandbox, so you should never again need to use -d repository_path in commands executed within that sandbox.

If you are checking out a sandbox from a remote repository, the repository path is slightly different than the path shown in the previous example. Example 2-11 shows a checkout from a remote repository.

Example 2-11. Remote repository checkout

$ cvs -d :ext:cvs:/home/cvs checkout cvsbook

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Once you've checked out project files into a sandbox, you can edit those files with your preferred editor. Changes are not synchronized with the repository until you run the cvs commit command. This command is best run from the root directory of your sandbox, and it must be run from within the sandbox.

Commit to the repository frequently. Rules of thumb for when to commit include "every time the code compiles cleanly" and "every day before lunch and before you leave."

In programming projects with several developers, try to avoid committing code that doesn't compile.

When you commit, CVS examines each directory and subdirectory below the current working directory. It searches for files that it is tracking that have changed, and commits all changes to the repository. See Example 2-12 for an example of committing files. Remember, the repository path is stored in the sandbox, so you don't need to specify the path explicitly in your cvs commit command.

Example 2-12. Committing files

$ cd ~/cvs/example
$ cvs commit
cvs commit: Examining .

If your repository is not on the local machine and your repository server doesn't have your SSH public key, CVS will ask for a password for the remote machine. If the server has the public key, your SSH client can use the private key to authenticate you.

If any files have been changed, CVS opens an editor to allow you to record a change message. By default, the editor is vi, just as when importing a project. Chapter 3 gives instructions on changing your editor.

I strongly recommend meaningful change notes. If you're trying to do a rollback and all you have are messages that say "fixed a few bugs," you won't know which revision to roll back to. See Example 2-13 for an example of a good change note.

Example 2-13. Enter a commit message

CVS:------------------------------------------------------------------
CVS: Enter Log.  Lines beginning with 'CVS:' are removed automatically

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The cvs update command checks your sandbox against the repository and downloads any changed files to the sandbox. It complements the cvs commit command, which uploads changes from the sandbox to the repository. Use the -d command option to download new directories as well. Example 2-16 shows the use of cvs update.

Example 2-16. Updating the sandbox

$ cvs update -d
cvs update: Updating .
U file2 
cvs update: Updating directory
$ ls
CVS  directory  file1     file2

As with committing, you should not have to specify the repository; it should be stored in the special CVS subdirectory in the sandbox. You must run cvs update from within the sandbox, and it is best to run it from the root directory of the sandbox to ensure that it checks all the subdirectories.

Note that -d means two different things, depending on where it is in the command. Recall that CVS commands take the form:

 cvs [cvs-options] command [command-options]

As a CVS option, -d defines the directory path. As a command option to the update command, -d downloads directories and files. This is explained more in Chapter 3.

As the update command runs, it generates a list of files that are modified. To the immediate left of each filename, you will see a single uppercase letter. Those letters report the status of each file listed, and they have the following meanings:

U filename: Updated successfully. A newer version in the repository has replaced your sandbox version.
A filename: Marked for addition but not yet added to the repository (need to run a cvs commit).
R filename

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

To add a file to a project in the repository, first create the file in your sandbox. Be sure to consider your project's structure and place the file in the correct directory. Then, issue the following command from the sandbox directory containing the file:

cvs add filename

This command marks the new file for inclusion in the repository. Directories are added with the same command. Files within a directory can't be added until the directory itself is added. A file is only marked for addition when you run cvs add ; it is actually added to the repository when the next cvs commit is run. A directory is added to the repository immediately. Example 2-19 shows a file being created and added to the repository. Remember, the file is not actually stored in the repository until the cvs commit command is run.

Example 2-19. Adding files

$ touch file3
$ cvs add file3
cvs add: scheduling file `file3' for addition
cvs add: use 'cvs commit' to add this file permanently
$ cvs commit
...
Log message editor opens
...
RCS file: /var/lib/cvsroot/example/file3,v
done
Checking in file3;
/var/lib/cvsroot/example/file3,v  &lt;--  file3
initial revision: 1.1
done

If you have binary files or other files that are not plain text, please see the section on binary files in Chapter 3 before adding them to the repository. These files should be added with the -kb command option.

As with committing, an editor window will open asking you to enter a log message describing the files to be added.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

To remove a file from the repository, first remove the file from the sandbox directory; then run the following command from the sandbox directory that contained the file:

cvs remove filename

The deletion does not take effect until the next cvs commit command is run; the file remains in the repository until then.

Example 2-20 shows a deletion. After thecvs commit is run, CVS doesn't remove the file entirely; it puts it in a special subdirectory in the repository called Attic . This saves the file history and enables the file to be returned to the repository later.

CVS opens an editor so you can record the reason for the file deletion, as it does when you commit changes.

Example 2-20. Removing a file

$ rm file3
$ cvs remove file3
cvs remove: scheduling `file3' for removal
cvs remove: use 'cvs commit' to remove this file permanently
$ cvs commit
...
Log message editor opens
...
Removing file3;" 9L, 308C written
/var/lib/cvsroot/example/file3,v  &lt;--  file3
new revision: delete; previous revision: 1.1
done

CVS does not remove directories from the repository, because doing so would break the change tracking. Use the -P flag to cvs checkout and cvs update to avoid empty directories in your sandbox.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS is a tool for improving project development and system maintainence. Like all tools, there are ways to make your use of it more effective. Here are some tricks for using CVS well:

Synchronize the clocks of computers sharing a repository to the same universal time. CVS relies on file timestamps to determine which files have changed.
Give each developer his own sandbox, and communicate all file changes through CVS. This maintains change tracking and prevents developers from irretrievably overwriting each other's work.
Update frequently, at least before starting work every day, to keep your sandbox current.
Commit frequently to keep your repository current. Programmers typically update every time their code compiles cleanly; other people may commit after completing each block of work.
Programming teams: use build-management tools and ensure that all files in the build are committed to the repository. Ensure that builds for testing or release come from the repository rather than a sandbox, but allow sandbox builds for programmers to do pre-alpha tests.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

This chapter provides a thorough discussion of the most critical CVS commands and topics. It is designed for end users who will not have to administrate the repository and who will not have to make changes that affect the entire project.

The commands explained in this chapter include checkout, commit, update, release, add, remove, and status. Other topics in this chapter include an explanation of sandboxes, merging, conflicts, binary and special files, keywords, editing files in CVS, and the CVS command syntax.

This chapter assumes that you have installed CVS, set up a repository, and created a project. Instructions for these tasks are in Chapter 2. Chapter 2 also touches on many of the commands in this chapter, but this chapter provides a full explanation of their uses.

CVS stores project data in a repository, but you don't work directly from the repository. You work from a sandbox. A sandbox may be on the same machine as the repository, on a machine on the same local network, or on a machine connected through the Internet or another wide-area network. Figure 3-1 illustrates some of these possibilities.

Figure 3-1: Repository and sandboxes

The sandbox is a directory on a client machine, that contains a copy of a project's files. Sandboxes are usually within a user's home directory. All of a given project's files should be underneath the top directory, but the files may be in as many subdirectories as are desired. Every subdirectory contains a special CVS directory, with metadata files.

If you want to install your project over several directories or outside of your home directory, that should be part of your build or installation script. The sandbox is a place for making changes; it's not a place for running the project.

Sandboxes and repositories do not exist on a one-to-one basis; many sandboxes may share the same repository. To ensure that the repository does not become unstable, the repository locks files that are being changed. (The locks are actually over entire directories.) Occasionally, a developer will get a warning message that the repository is waiting on a lock, as shown in Example 3-1.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS stores project data in a repository, but you don't work directly from the repository. You work from a sandbox. A sandbox may be on the same machine as the repository, on a machine on the same local network, or on a machine connected through the Internet or another wide-area network. Figure 3-1 illustrates some of these possibilities.

Figure 3-1: Repository and sandboxes

The sandbox is a directory on a client machine, that contains a copy of a project's files. Sandboxes are usually within a user's home directory. All of a given project's files should be underneath the top directory, but the files may be in as many subdirectories as are desired. Every subdirectory contains a special CVS directory, with metadata files.

If you want to install your project over several directories or outside of your home directory, that should be part of your build or installation script. The sandbox is a place for making changes; it's not a place for running the project.

Sandboxes and repositories do not exist on a one-to-one basis; many sandboxes may share the same repository. To ensure that the repository does not become unstable, the repository locks files that are being changed. (The locks are actually over entire directories.) Occasionally, a developer will get a warning message that the repository is waiting on a lock, as shown in Example 3-1.

Example 3-1. Lock message

cvs server: [23:20:43] waiting for jenn's lock in /var/lib/cvs/wizzard/src

This message indicates that CVS is waiting on the other developer's lock in the specified directory. If a CVS process is killed before it's finished tidying up, a lock file may be created and not cleared. If CVS seems to be taking an inordinate amount of time to clear a lock, your repository administrator can clear it manually. Chapter 6 provides instructions and an example of how to do so.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

A sandbox is a local copy of a project's files, used to make changes and test work. Each developer should work from her own sandbox on a computer that is convenient to her.

The CVS repository contains the master copies of a project's files and their full histories. The repository may be on the same machine as the sandbox or on a remote machine accessed across a network. The repository is explained more fully in Chapter 6.

Every directory in the sandbox contains a CVS subdirectory. This directory has several files; the most important are Root, Repository, and Entries. The Root file contains the path to the sandbox's repository, the Repository file contains the subpath within the repository that leads to the directory in question, and the Entries file holds metadata about the files in the directory. The CVS subdirectory is explained more fully in Chapter 6.

Files lose their permissions when they are transferred to the repository. CVS normally will check out files with read and write permissions, but it can be configured to check them out as read-only. The person who checks a file out into the sandbox becomes the file's owner.

CVS works on many operating systems, each of which has its own way of recording ownership of files. The repository might not be on the same machine or have the same operating system as the sandbox. These circumstances may cause files to lose their ownerships and group memberships when the files are transferred to the repository, especially if the owning user does not exist on the repository machine. If the sandbox is connected to the repository through a proxy or network tunnel, the existence of appropriate users and groups on intermediate machines can also affect the ownership of files.

Group ownership of files in the repository is important, because CVS prevents users from checking out files they do not have read access to. Chapter 6 explains ownership and security issues with CVS.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Files are edited in the sandbox, but changes to the sandbox have no effect on the repository until they are committed. The cvs commit command uploads changes from the sandbox to the repository. After determining which files need to be changed in the repository, cvs commit opens an editor and expects you to enter a log message.

Section 3.1.3 earlier in this chapter explains how to change the default editor.

The syntax of cvs commit is:

 cvs [cvs-options] commit [command-options] [filename]

cvs commit has only a few options:

-l: Perform a local, nonrecursive commit operation on the current working directory only.
-R: Perform a recursive commit operation on all subdirectories, as well as the current directory (default).
-m message: Provide a log message.
-F filename: Provide a log message from the specified file.
-r revision: Set an updated revision number (not recommended for novice users).

Example 3-3 shows a typical cvs commit. The vertical ellipsis denotes the point at which CVS normally calls the editor. Example 3-4 shows the default text displayed in the editor and the log message for this commit.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The cvs status command is a quick way to determine which files are up-to-date and which need to be committed or merged.

Files that have not been added to the repository are prefixed with a question mark (?). Files stored in CVS are shown with the filename, the current status, the working (or sandbox) revision, the revision currently stored in the repository and its location in the repository, and the sticky state of the file. Stickiness is explained in Chapter 4.

The syntax of cvs status is:

 cvs [cvs-options] status [command-options] [filename]

The status command has only three options:

-l: Perform local, nonrecursive operation on this directory only.
-R: Perform recursive operation on all subdirectories, as well as the current directory (default).
-v: Use verbose mode (display information about tags as well).

Example 3-5 shows the CVS status report for the wizzard.h file.

Example 3-5. Output from the cvs status command

=  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  = =  =
File: wizzard.h             Status: Up-to-date
   
   Working revision:    1.5
   Repository revision: 1.5     /var/lib/cvs/wizzard/src/wizzard.h,v
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)

A file may be in one of the following states:

Up-to-date

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The cvs commit command uploads changes from the sandbox to the repository; cvs update downloads changes from the repository to the sandbox. The two commands complement each other, and you need to call both to keep the sandbox synchronized with the repository. Use cvs commitwhen you have changed sandbox files since your last commit; use cvs update when you know that (or wish to check whether) the repository has been changed since you last updated.

cvs update attempts to preserve any changes you have made to your sandbox since you last synchronized it with the repository. These changes will be merged into the files retrieved from the repository. If you intend to overwrite your sandbox files with a clean repository copy, use the -C (clean) option in conjunction with any other options. Most often, you will use -C when you want to discard changes, but you can also use the -r (retrieve by revision), -D (retrieve by date), or -A(clear sticky tags) options.

Example 3-6 shows output from cvs update executed with the -d option. The -d option instructs CVS to download new directories from the repository to the sandbox.

Example 3-6. Using cvs update

bash-2.05a$ cvs update -d
cvs server: Updating .
cvs server: Updating doc
cvs server: Updating doc/design
U doc/design/Analysis.rtf
U doc/design/Specification.rtf
cvs server: Updating doc/plan
U doc/plan/Schedule.rtf
cvs server: Updating lib
cvs server: Updating man
cvs server: Updating src
M src/wizzard.h

cvs update displays symbols next to each file it downloads. The symbols report file status, similar to those reported by cvs status. You'll see the following symbols in cvs update command output:

A filename

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Use cvs add to add a file or directory to the repository. Using cvs add on a file marks the file as needing to be added when cvs commit is run. Running cvs add on a directory adds the directory to the repository and the CVS subdirectory to the directory.

The Attic and CVSdirectories are special directories that CVS uses for its own purposes. Do not make a file or directory with these names.

If you attempt to commit and get an error message that includes *PANIC* administration files missing, you may have created a file or directory named CVS. This message means that CVS could not find the Repository file in the CVS subdirectory of the sandbox directory it is trying to commit.

You can use cvs remove to remove a file that has been added but not committed. This removes the marking in the CVS subdirectory and doesn't record the aborted addition in the repository's history. Similarly, you can use cvs add to abort a file removal; it will resurrect the file without recording the aborted removal.

The file or directory to be added must exist within the sandbox, and a directory must not contain a file or subdirectory named CVS.

Files and directories are case-sensitive in the repository. If you are using a CVS client or operating system that is not case-sensitive, you may encounter problems. Avoid using file or directory names that would be the same if case were not an issue.

In the process of adding a file, CVS strips trailing slashes and any special CVS files from the arguments, then checks for name conflicts (including some case-comparison testing). If CVS detects a name conflict, it notifies the user and does not add the file or directory.

cvs add uses the following syntax:

cvs [cvs-options] add [command-options] filename

The available options are -k, followed by any of the keyword flags, and

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The cvs remove command is used to mark a file as removed in the repository. The file isn't actually removed from the repository; it simply is stored in a special directory called Attic, so that its earlier revisions can be recalled. The file is no longer sent to sandboxes, and it is removed from existing sandboxes at the next cvs update, which displays the message cvs server: filename is no longer in the repository.

A removal must be committed before it affects the repository. If you notice that you accidentally removed a file you need (before you run cvs commit), you can use cvs add to undo the removal and then use cvs update to retrieve the removed file. This process leaves no record in the repository. Similarly, if a file has been added but not committed, cvs remove undoes the addition and leaves no record in the repository.

If someone else modifies a removed file before the removal is committed, the commit will fail and report a conflict. Resolve the conflict by unremoving the file with cvs add, checking the changes with cvs update or cvs diff, and removing the file again if desired. I strongly recommend speaking with the person who modified the file before you resolve such a conflict, lest you remove a file that should be retained.

To use cvs remove on a file, the file must not exist in the sandbox or you must call the cvs remove command with -f. Usually, I delete the file from the sandbox before running cvs remove.

The syntax for cvs remove is:

cvs [cvs-options] remove [command-options] filename

cvs remove has the following options:

-f: Delete the file from the sandbox.
-l: Perform a local, nonrecursive operation on this directory only.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

There is no CVS command designed specifically to move a file or file directory. In fact, CVS's design doesn't accomodate such moves. However, you can work around this limitation using a combination of CVS commands, or by altering the repository using operating-system commands. Moving files can make project history difficult to track, because then a file's history is recorded across two different files in different locations. Minimize this potential source of confusion by recording the new and old locations with meaningful log messages.

To rename a file or directory at the operating-system level, move it from the old filename to the new filename. For example, use the Unix mv command.

The recommended way to move a file is to use cvs remove followed by cvs add, with messages that state where the file was moved from and to. This method preserves the file's history and allows reversion to earlier versions of the project in its old location. However, the messages stored with the add and remove commands are the only record of the move. Example 3-19 shows this method being used to rename the wizzard.h file.

Example 3-19. Renaming a file

bash-2.05a$ mv wizzard.h config.h
bash-2.05a$ cvs remove wizzard.h
cvs server: scheduling `wizzard.h' for removal
cvs server: use 'cvs commit' to remove this file permanently
bash-2.05a$ cvs add config.h
cvs server: scheduling file `config.h' for addition
cvs server: use 'cvs commit' to add this file permanently
bash-2.05a$ cvs commit
.
.
.
Moving src/wizzard.h to src/config.h
CVS: ---------------------------------------------------------------------
CVS: Enter Log.  Lines beginning with `CVS:' are removed automatically
CVS: 
CVS: Committing in .
CVS: 
CVS: Added Files:
CVS:  config.h 
CVS: Removed Files:
CVS:  wizzard.h 
CVS: ---------------------------------------------------------------------
.
.
.
RCS file: /var/lib/cvs/wizzard/src/config.h,v
done
Checking in config.h;
/var/lib/cvs/wizzard/src/config.h,v  <--  config.h
initial revision: 1.1
done
Removing wizzard.h;
/var/lib/cvs/wizzard/src/wizzard.h,v  <--  wizzard.h
new revision: delete; previous revision: 1.5
done

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The cvs release command should be used before you delete a sandbox. CVS first checks whether there are any files with uncommitted changes; then, if all is well, CVS runs cvs unedit on each file to signal that you no longer intend to edit the files, and writes to the history file in the repository to state that the sandbox was released. CVS also reports on files and directories that are not currently stored in the repository.

If there are uncommitted changes, CVS alerts you to the changes and does not release the sandbox. You can use cvs commit to commit the changes, remove the changed files manually, or use cvs update -A to revert to a state where you can release the sandbox (and lose the changed data).

It's not strictly necessary to use cvs releasebefore deleting a sandbox. You can delete a sandbox with no effect on the repository. However, if you get into the habit of using cvs release, you'll remember to use it the one time you do need to run an unedit or when you have made an uncommitted but important change.

The syntax for cvs release is:

cvs [cvs-options] release [-d] directory

The only option to cvs release is -d, which deletes the sandbox after checking it for uncommitted changes. You can use cvs release on an entire sandbox or on a subdirectory within the sandbox.

When you execute cvs release, you must specify a directory, but you can use a dot (.) to indicate your current working directory. Example 3-20 shows cvs release being used to release the wizzard sandbox. Note that a dot is used to specify the current working directory as the sandbox to release.

Example 3-20. Using cvs release

bash-2.05a$ cvs release .
cvs server: warning: src/wizzard.h is not (any longer) pertinent
? src/test
? src/test.c
U src/config.h
U src/main.c
You have [0] altered files in this repository.
Are you sure you want to release directory `.': n
** `release' aborted by user choice.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS recognizes keywords that can be included in any source file other than a binary file. When CVS finds a keyword in a file it is checking out, it expands the keyword to provide metadata about the latest revision of the file. CVS keywords take the following form:

$Keyword$

Example 3-21 shows a file that includes CVS keywords.

Example 3-21. CVS keywords

# Makefile for the Wizzard project
# First created by J Vesperman, 1 September 2002
#
# Current revision $Revision: 1.6 $
# On branch $Name:  $
# Latest change by $Author: chodacki $ on $Date: 2004/04/16 16:15:52 $
   
# Initial declarations
CC=gcc
SUBDIRS = man doc src lib
   
# Declaring phony targets
.PHONY: all clean install
   
all: wizzard
      echo "all: make complete"
   
clean:
      rm -f src/*.o
      rm -f wizzard
      echo "clean: make complete"
   
.
.
.
   
# Log record for Makefile changes:
# $Log: ch03.xml,v $
# Revision 1.6  2004/04/16 16:15:52  chodacki
# sfcleanup fixes
#
# Revision 1.5  2003/07/11 20:00:23  madd
# madd final SC edits
#
# Revision 1.4  2003/07/09 21:31:56  madd
# madd SC edits
#
# Revision 1.3  2003/07/07 21:52:50  madd
# madd SC edits
#
# Revision 1.2  2003/06/27 21:47:43  madd
# madd R2 conversion edits
#
# Revision 1.1  2003/06/26 22:22:10  madd
# Initial revision
#

Example 3-21 shows a makefile. The keywords are expanded when the file is checked out or updated. Example 3-22 shows the resulting expansions.

Example 3-22. Expanded keywords

# Current revision $Revision: 1.6 $
# On branch $Name:  $
# Latest change by $Author: chodacki $ on $Date: 2004/04/16 16:15:52 $
   
# Initial declarations
CC=gcc
SUBDIRS = man doc src lib
   
.
.
.
   
# Log record for Makefile changes:
# $Log: ch03.xml,v $
# Revision 1.6  2004/04/16 16:15:52  chodacki
# sfcleanup fixes
#
# Revision 1.5  2003/07/11 20:00:23  madd
# madd final SC edits
#
# Revision 1.4  2003/07/09 21:31:56  madd
# madd SC edits
#
# Revision 1.3  2003/07/07 21:52:50  madd
# madd SC edits
#
# Revision 1.2  2003/06/27 21:47:43  madd
# madd R2 conversion edits
#
# Revision 1.1  2003/06/26 22:22:10  madd
# Initial revision
#
# Revision 1.2  2002/09/01 06:57:23  jenn
# Initial code in the Makefile.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The default CVS method of handling file conflicts works well for text files, because CVS can determine which lines have changed and add or remove them as appropriate. It doesn't work well on binary files, because such files are not usually built around lines of text separated by carriage returns.

Some files with textual content are not actually text files. Files such as those created by Microsoft Word or OpenOffice should be flagged as binary, because line-by-line merging and keyword expansion could damage the saved data.

CVS doesn't work for device files, symbolic links, or other files that cannot be modified and moved. Rather than trying to store these files in CVS, include the commands to create or connect them in your build scripts.

For binary files, CVS uses a different method of conflict resolution. The two methods CVS has available are MERGE and COPY. MERGE is the default CVS method. COPY instructs CVS to provide the user with both versions of the file if there is a conflict, so the user can blend the changes manually and recommit.

Binary files should be added to CVS using the -kb command option to cvs add. If the expansion mode is not set at the time the file is added, the -kb command option to cvs admin will set the mode retroactively. This informs CVS not to expand keywords, not to modify line endings, and to use the COPY method of conflict resolution. Example 3-23 shows the use of these command options.

Example 3-23. Setting keyword expansion for binary files

bash-2.05a$ cvs add -kb Requirements.doc 
cvs server: scheduling file `Requirements.doc' for addition
cvs server: use 'cvs commit' to add this file permanently
bash-2.05a$ cvs add AcceptanceTest.doc 
cvs server: scheduling file `AcceptanceTest.doc' for addition
cvs server: use 'cvs commit' to add this file permanently
bash-2.05a$

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

If you find yourself regularly using the same options with a command, you can use the .cvsrc file to set default options and minimize your typing. If the .cvsrc file is in your home directory on your client machine, CVS will read the file, look for the CVS command you are currently running, and will run the command with the options specified for that command in the file. To temporarily avoid parsing the .cvsrc file, use the -f CVS option.

The .cvsrc file format is one line per command. Start a line with the command you want to modify, followed by the options you want as the default. You can also specify default CVS options in the .cvsrc file. To do so, use cvs as the command.

Example 3-25 shows a .cvsrcfile. This file specifies a default description for adding files, specifies (using -P) that update and checkout prune empty directories, and specifies (using -q) that CVS run quietly, but not as quietly as it would with the -Q option.

Example 3-25. A .cvsrc file

add -m "Part of the wizzard project"
update -P
checkout -P
cvs -q

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

One of the most helpful yet underused facilities of CVS is the tag . CVS's tagging feature allows you to label a revision for later retrieval. This feature also allows you to fork development so that you can work on two or more versions of your project simultaneously. The version that has been forked off is called a branch , and the main line of development is called the trunk .

This chapter explains tags, branches, and how to merge branches and trunks. It also discusses why and when to branch and provides strategies and hints for using branches effectively in your project.

CVS allows you to retrieve any checked-in revision of a file. While retrieving revisions of individual files is useful, it's even more useful to be able to retrieve the compatible set of revisions that make up a complete, functional version of a project, such as all the revisions that become release 1.0 of a program, or that become the first edition of a book.

Tagging is a way of marking a group of file revisions as belonging together. You can't use the revision numbers for this purpose, because revision 2.3 of one file might belong with revision 2.17 of another. Figure 4-1 shows a group of file revision numbers, with a string denoting which revision numbers belong to the same release.

Figure 4-1: File revisions that belong together

CVS allows you to create a single tag that denotes all the file revisions that connect to that virtual string. When you want to look at all the file revisions that belong to a tag, CVS can "pull the string" to locate the tagged revisions. Figure 4-2 shows the same group of files, with the string pulled tight to show which set of revisions belong to that tag.

Figure 4-2: Tagged file revisions

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS allows you to retrieve any checked-in revision of a file. While retrieving revisions of individual files is useful, it's even more useful to be able to retrieve the compatible set of revisions that make up a complete, functional version of a project, such as all the revisions that become release 1.0 of a program, or that become the first edition of a book.

Tagging is a way of marking a group of file revisions as belonging together. You can't use the revision numbers for this purpose, because revision 2.3 of one file might belong with revision 2.17 of another. Figure 4-1 shows a group of file revision numbers, with a string denoting which revision numbers belong to the same release.

Figure 4-1: File revisions that belong together

CVS allows you to create a single tag that denotes all the file revisions that connect to that virtual string. When you want to look at all the file revisions that belong to a tag, CVS can "pull the string" to locate the tagged revisions. Figure 4-2 shows the same group of files, with the string pulled tight to show which set of revisions belong to that tag.

Figure 4-2: Tagged file revisions

A tag can be used to mark a specific revision of a single file or a specific set of revisions of a group of files—in essence, naming the string. The tag then gives you a convenient way to retrieve that revision or matched set of revisions. Remembering the significance of a text string is much easier than remembering a version number. Tags are often used to record the version number used by the developers, rather than the CVS revision number, which is used primarily as a CVS internal designation.

Tag names must start with a letter and can contain alphanumeric characters, hyphens (-), and underscores (_). Each tag must be unique within the tagged file. You tag files with the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Stickiness is an important concept in CVS, especially when talking about tagging and branching. Stickiness is primarily internal to CVS, but it affects what can be done in a sandbox.

When a file in a sandbox has a persistent state that is not the default state in the repository, the persistent state is said to be sticky. A sandbox copy of a file can be set to a specific revision, belong to a branch, or have specific keyword options. Any of these things can cause a file to be sticky.

A file can be set to a specific revision by being retrieved from the repository with a tag, revision number, or date. If the file is retrieved with a date, it is said to have a sticky date. If it is retrieved with a tag, it is said to have a sticky tag , and if it is retrieved with a revision number, it is said to have a sticky revision.

Along the same lines, a sandbox file that belongs to a branch is said to have a sticky branch , and a sandbox file with sandbox-specific keywords has sticky keywords .

A sticky state applies to all commands run on the file. A file with a sticky date, revision, or nonbranch tag will not be updated to a more recent copy; nor can such files be committed. A file with a sticky branch is always committed to or updated from the branch in question.

Sticky states on a file can be viewed with cvs status. For example, use the command cvs status index.htm to see the status for the index.htm file. Example 4-8 shows a cvs status report that lists a sticky branch.

Example 4-8. Viewing a sticky file

bash-2.05a$ cvs status main.c
=  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =
File: main.c                Status: Up-to-date
   
   Working revision:     1.9
   Repository revision:  1.9     /var/lib/cvs/wizzard/src/main.c,v
   Sticky Tag:           beta_0-1_branch (branch: 1.9.2)
   Sticky Date:          (none)
   Sticky Options:       (none)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

In the introduction to this chapter, I defined a branch as a forked line of development in your project, with the line that has been forked off called the branch, and the main line the trunk. CVS builds the branch and the trunk from the same source data, up until the point at which they diverge, which is called the base of the branch. From that point, CVS stores the changes made to the branch separately from the changes in the trunk. Revisions on the branch are given their own revision numbers, based on the revision number of the base of the branch.

You can branch a single file, any group of files, or a whole project just as you can tag individual files or any group of them. I usually recommend branching a project. In my experience, if you branch one file, you will eventually need to branch others in the project for the same reason. It is much easier to keep track of a single branch over the whole project than a group of unrelated branches of individual files.

A tag marks a specific revision of each tagged file, and a sandbox checked out with that tag cannot be changed. In contrast, a branch creates revisions that can be edited, committed, checked out, updated, and tagged independently of the revisions on the trunk. In many ways, a branch can be treated as an independant development line of a project.

You can tag a file with any number of tags, as long as each tag name in that file is unique. CVS also allows you to tag branch revisions with several tags on the branch. CVS relies on each tag and branch name to be unique within each file, so it considers the branch name to be a tag name.

A branch is an ongoing line of development, and the tags on the branch mark the specific revisions when significant events occur. Though branches are created using the cvs tag command, branches and tags are different things. A branch represents multiple revisions and a tag represents a single revision.

For some commands, such as cvs diff

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

This section explains the basis of branching strategies and the two main philosophies of branching. It also provides some answers to the question of when and why you should branch on a project.

The general rule of thumb for branching is: keep the main line of development on the trunk; everything else can be branched. The problem is determining the main line of development. Should the trunk contain stable code or unstable code? Should each release be branched when it goes to be tested? Should new features be developed on the trunk or on a branch?

These decisions all stem from two distinct definitions of "the main line of development." These two definitions result in two different branching philosophies, which can be termed basically stable and basically unstable.

Section 4.4.1.1: Basically stable

The basically stable branching philosophy states that the trunk should contain project data that is always close to being ready for release. Branches are used for development, bug fixes, prerelease QA (quality assurance), and refactoring. Branches are also used for experimental code.

The strictest variation of this philosophy states that nothing should be merged to the trunk until it has been through QA. This ensures that at any time a release candidate can be taken from the trunk, put through a small amount of QA, and then published or sold.

More lenient variations of this philosophy allow anything that passes developer unit-testing to be merged into the trunk. Such a relaxed approach requires a release candidate to be branched off and put through a full QA analysis before publication.

Advantages of the basically stable method include the following:

You can take a release off the trunk at any time, run it through QA, and publish it.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

This chapter explains how CVS can be used for source or content control — how to manage a group of developers working together on a project without having them overwrite each other's work, causing loss of data. It also describes commands that show what each person has done to a file.

The problem of source control occurs when you don't have any management software. If you have a central location for data and two people are using the same storage, such as the same file, the second person to save a file can overwrite the first person's changes. Source control software can prevent this, by either capturing both sets of changes and merging them together, or by preventing two people from having the same file checked out at the same time.

CVS is designed to allow developers to work simultaneously on a file. Several people can work on the same file, each in their own sandbox, and CVS tries to merge their changes to the data in the central repository. If the changes can't be merged easily, the developer who commits the second set of changes is asked to resolve the conflict. This pattern is explained in Chapter 3.

An alternative to simultaneous development is exclusive development, where one developer at a time has the editing rights for a file. Some development teams prefer to use exclusive development, which is effective for files that can't be merged. CVS supports the exclusive development of files with a choice of two methods:

The first method permits, but does not enforce, exclusive development. This method uses the cvs watch, cvs edit, and cvs unedit command set.
The second method uses the cvs admin command to emulate file locking with reserved checkouts and relies on the rcslock script in the contrib directory of the CVS source code. This method requires the assistance of the repository administrator.

Whether you use exclusive or simultaneous development, source control works only if your project members use it. It is also essential that they communicate the basic design and structure of the project with each other. No source control system can take the place of a shared vision of the project.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Simultaneous development allows multiple developers to work on the same file at the same time. If you and your coworker are working on different sections of a file, you can both edit the file and then have a program (such as CVS) merge the two versions of the file. Simultaneous development is also useful when you have developers distributed across many time zones, as it eliminates the need to check with other team members before editing a file.

CVS supports simultaneous development without requiring any configuration changes or setup. Simultaneous development is most helpful when you are using text or other line-based files, because CVS merges are based on the changes in lines. CVS is less able to merge binary files.

When multiple developers use the same repository directory, each should check out her own sandbox, develop in that sandbox, commit to the repository frequently, and update frequently. CVS merges most changes automatically, and if you update and commit frequently, there should be few cases where a human has to edit the changes.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS provides a set of commands to notify users when a file is being edited or committed. You can use these commands to monitor what each member of your team is doing and reduce the necessity of merging files when cvs update is run. Together, the cvs watch , cvs edit, and cvs unedit commands make up the watch method of exclusive development, which is a lightly enforced method of exclusive development.

The watch method requires the repository administrator to set up the notify and users files in the CVSROOT directory of the CVS repository; it requires the developers to check whether a file is being edited before they attempt to edit it.

Use cvs watch like this:

Check out your sandbox, including the files you want to watch.
Issue the cvs watch on command to mark files for watching. (This does not set you as the watcher for the files; it just informs CVS that the files can be watched.) Once a file has been marked for watching, it remains marked unless it is cleared with cvs watch off.

You need to use cvs watch on for a file only once, unless someone clears the setting. Usually, your project leader decides which files can be watched and will mark those files for watching.
Issue the cvs watch add commandto set yourself as a watcher of the files you want to watch.
Issue cvs edit to inform CVS and other users that you intend to edit a specific file. Other users watching the file will be notified that you are editing it.
Edit the file in any editor.
Commit your changes with cvs commit. This saves the changes to the repository and releases the file for others to edit. CVS notifies other users watching the file that you have committed it.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS has a method of exclusive development that is based on reserving the ability to commit files, so that only a single user can commit a reserved file. This is useful when you want to enforce exclusive development, especially when you have files that cannot be merged and users who are not comfortable with the honor system that cvs watch relies on.

This method requires the rcslock script (distributed in the contrib subdirectory of the CVS source code), file locking set to strict (the CVS default), the assistance of the repository administrator, and the active support of the developers. The rcslock script is provided as is; currently, it is an unsupported part of the CVS distribution.

File locking is set to strict by default in CVS, so there should be no need to set it that way manually. You can confirm the lock status of a file with the command cvs log -h filename.

Do not use the cvs admin -U command on any files in your project. This sets file locking to nonstrict and can cause problems. File locks can be set strict again with cvs admin -L.

The rcslock script is distributed with the CVS source code. Chapter 2 includes the URL for the CVS source code, and most Linux or Unix packaging systems include an option to install the source from the package. In CVS 1.11.5, the rcslock script is called rcslock.in(in previous versions, it was called rcslock.pl). The CVS build script attempts to generate a version called rcslock, with a Perl invocation as the first line.

Install the rcslock script by copying it from the contrib directory to a sensible location and ensuring that your CVS users have permission to execute it. I recommend using /usr/local/lib/cvs as the location for this script, because /usr/local/lib is a standard location for components of locally installed software such as CVS. Edit the commitinfo file in the repository's CVSROOT

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

As your project develops, you sometimes need to compare a current revision with an old one, or compare two older revisions with each other. This usually happens when several developers are working on the same file and you need to know which changes were made to a file since you last worked on it.

The cvs diff command compares two revisions of a file and displays the differences. It uses a version of the GNU diff program internal to CVS; this code is also used when revisions are merged during cvs update.

The diff command and the similar rdiff command are also useful for creating patches to be installed by the GNU patch program.

cvs diff has the following syntax:

cvs [cvs-options] diff  [command_options] [filenames]

You can call cvs diff with filenames, directories, or module names. If you don't give a filename, the current working directory is the default.

Usually, you call cvs diff with at least one -r tag or -D date command option. If you invoke it with a single -r or -D parameter, CVS compares the current copy in the working directory with the version in the repository. For example, if you check out revision 1.6 of Makefile, edit the file, then run cvs diff -r 1.6 Makefile, diff displays the changes you made to Makefile since you checked it out.

If you invoke cvs diff with two -ror -D options, CVS compares the two revisions against each other. The command cvs diff -r 1.5 -r 1.7 Makefile displays the changes between revisions 1.5 and 1.7.

Example 5-14 shows a diff command that compares revisions 1.2 and 1.3 of the Makefile file, with the option to display a few lines of context around each change. The output starts with a header listing the filename, the repository copy of the file (listed as RCS file), the revisions to be retrieved, the diff options, and the times the revisions were committed.

diff then shows the sections that were changed. The

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The cvs annotate command displays the most recent change for each line of a file in the repository. This is very helpful when you need to know which change broke the compilation or who rewrote a key paragraph in the documentation incorrectly. This command works off the repository copy, not the sandbox copy, so it does not show any changes in the sandbox that were not committed.

For each line, cvs annotate shows the revision number for the last change, the user, the date, and the contents of the line. This is a quick way of discovering who made which change. Example 5-17 shows some of the annotations for the wizzard.h file.

Example 5-17. Using cvs annotate

bash-2.05a$ cvs annotate src/wizzard.h
Annotations for src/wizzard.h
***************
1.6     (doppel   15-Sep-02): #include "config.h"   /* using autoconf */
1.6     (doppel   15-Sep-02): #include "options.h"  /* manual options that can't 
1.1     (jenn     11-Sep-02): 
1.2     (jenn     13-Sep-02): #define TRUE 1
1.2     (jenn     13-Sep-02): #define FALSE 0

cvs annotate has the following syntax:

cvs [cvs-options] annotate [command-options] [filenames]

If you don't give a filename, cvs annotate attempts to run annotate on all the files in the current sandbox. The filenames can be directories or modules.

annotate doesn't work correctly on binary files. CVS tries to display them as text files, which can trigger the bell character and mess with your terminal window.

Use the -F option to run cvs annotate on binary files. You can select which revision to display with -D date and -r revision (or tag), and you can use the -foption to force CVS to use the most recent revision on the trunk if no revision matches the specified date, revision, or tag. cvs annotate uses the usual -l and -R options to control local and recursive operation, respectively.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The cvs log command displays information about files, directories, or modules. You pass a parameter to specify which file, directory, or module you are interested in. If you don't specify anything, cvs log displays log information about all files in the current sandbox directory. The user-provided part of this log information is entered when you run cvs commit or when you set the -m command option to cvs add.

cvs log is often used to help decide which two revisions to use to create a patch file, to determine a branch point, or to provide a quick guide to what the other developers are doing in a multiuser environment. Informative log messages are very important for all of these uses.

The options to cvs log reduce the amount of information it shows. By default, it displays everything it can. For each file, it displays a header; then, for each revision of the file it displays the revision number, date, author, state, log message, and number of lines added and deleted in that revision.

Example 5-18 shows a simple use of cvs log. Note that the keyword-substitution mode is the default mode, generating both keyword and value, and that the log message in revision 1.1 mentions both files that were added at the time.

Example 5-18. Using cvs log

bash-2.05a$ cvs log main.c
                     
RCS file: /var/lib/cvs/wizzard/src/main.c,v
Working file: main.c
head: 1.9
branch:
locks: strict
access list:
symbolic names:
     beta_0-1_branch: 1.9.0.2
     beta_0-1_branch_root: 1.9
     pre_beta_0-1: 1.8
keyword substitution: kv
total revisions: 9;     selected revisions: 9
description:
----------------------------
revision 1.9
date: 2002/09/12 08:14:19;  author: jenn;  state: Exp;  lines: +0 -0
Final test of re-addition methods.
.
.
.
----------------------------
revision 1.1
date: 2002/09/11 13:33:13;  author: jenn;  state: Exp;
Added main.c: parses parameters and calls functions in other files.
Added wizzard.h: defines compile-time global variables.
=  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

This chapter is about the repository and the projects stored in it. If you want a quick guide to creating an initial repository, see the instructions in Chapter 2.

Topics covered in this chapter include repository creation, configuration, security, backup, and recovery. This chapter also covers the structure of the repository and the sandbox, the file locking CVS uses internally, how to edit the repository manually, and the CVS administrative files and environment variables.

CVS uses the term CVSROOT in two different ways. As the environment variable, it refers to the root directory of the repository. However, inside the repository is a directory called CVSROOT. To avoid confusion, this chapter never refers to the root directory of the repository as CVSROOT, and, except when mentioning the environment variable, this chapter uses the term solely to refer to the CVSROOT subdirectory of the repository root directory.

If your repository is in /var/lib/cvs, then /var/lib/cvs is the repository root directory and /var/lib/cvs/CVSROOT is the repository's CVSROOT directory.

The repository root directory and the administrative files should be owned by a user made specifically for CVS; typically, the user is named cvs. This reduces the damage a malicious or careless user can do to the repository, as long as they don't have root access.

To create a repository, create the repository root directory on the computer that will act as the CVS server and ensure that the root directory is owned by the user who will ultimately own the repository. Execute the command cvs -d repository_root_directory init,where repository_root_directory is the name of your directory, to set up that directory as a CVS repository. The root directory given must be an absolute path, not a relative path. Example 2-5 in Chapter 2 shows repository creation.

The cvs init command sets up the directory as a CVS repository by creating the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The repository root directory and the administrative files should be owned by a user made specifically for CVS; typically, the user is named cvs. This reduces the damage a malicious or careless user can do to the repository, as long as they don't have root access.

To create a repository, create the repository root directory on the computer that will act as the CVS server and ensure that the root directory is owned by the user who will ultimately own the repository. Execute the command cvs -d repository_root_directory init,where repository_root_directory is the name of your directory, to set up that directory as a CVS repository. The root directory given must be an absolute path, not a relative path. Example 2-5 in Chapter 2 shows repository creation.

The cvs init command sets up the directory as a CVS repository by creating the CVSROOT subdirectory and the initial files for that directory, with their default configurations.

For any project, ensure there is enough room for three times the expected final size of the project. If you intend to store binary files, multiply their expected size by at least five. Monitor the repository's partition; your users may have a use pattern that requires more or less space than this.

For most projects, the amount of RAM on the repository server is not an issue. CVS is usually modest in its memory requirements, and a server with 32MB of RAM can handle most repositories. The two major areas of memory use are large checkouts and large diffs.

For each checkout request from a client, CVS spawns two processes. The smaller process uses a negligible amount of memory, but the larger consumes at least two megabytes and can grow to just over the size of the files in the directory being checked out. Fortunately, the larger process can use swap space rather than physical memory. Allow enough memory for several of these processes to run simultaneously, and base your calculations on the project directory that occupies the most disk space.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

A CVS repository that is no longer needed can be removed as you would remove a normal directory tree. All the information CVS stores about the repository and the projects in it are stored within the repository tree, most of it in the CVSROOT subdirectory of that repository.

If you have edited the scripting files in the CVSROOT directory, they may refer to scripts stored elsewhere. Check the scripting files; if the referenced scripts are no longer needed, they can also be removed.

Once you have backed up any projects you may need to refer to later, remove the repository with rm -rf repository_root_directory.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The security of your projects relies on the security of your CVS repository, the repository's computer and its environment, all the computers that contain sandboxes, your access method, your backup storage, and your developer's working environments. The security of access methods is covered in Chapter 8. General computer security is outside the scope of this book, but you should consider it when securing your repository.

Sandboxes are checked out of the repository with the username of the user who creates them or does the checking out. If the client's computer has a group that matches the group ownership of files in the repository, files in the sandbox are usually stored with that group ownership.

Permissions in a sandbox depend on the settings for new files in the sandbox computer's operating system, on whether the user has the CVSREAD environment variable set, and on whether the files are being watched with the cvs watch commands. If a file is imported or added as executable, it is set as executable in the repository and the executable setting is preserved in the sandboxes. The CVSREAD environment variable is described in Section 6.10, later in this chapter.

Repository security is more complex than sandbox security, and it is based on the filesystem security for the operating system that the repository is running under. The specific instructions in this section are based on traditional Unix and Linux filesystem permissions, but the principles can be used to secure a repository running under systems with more extensive security options, such as Access Control Lists (ACLs).

Secure the repository root directory so that only users who are allowed to create new projects have write access. Users who will be using existing repository projects, even though they may be creating and writing to project files, should have read access to this directory.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

A CVS repository is composed of the special CVSROOT administrative directory and any project directories you create. All the CVS administrative files and configuration files are kept in CVSROOT.

The project directories contain the project's files and subdirectories. The project's files are stored in RCS format and have a ,v file suffix.

Any project directory or subdirectory may contain Attic or CVS directories. An Attic subdirectory stores any file from the directory it's part of that doesn't exist on the trunk (the main development line for the file). The Attic directory is explained in Chapter 3. A CVS subdirectory stores metadata for the files in its directory.

The server also stores files in a temporary directory set by either the TMPDIR environment variable or the -T command-line option. These files are under a directory calledcvs-serverPID , where PID is the process ID of the server. If the server is shut down and unable to clean up after itself, the files may be left in place. They can be removed safely if there is no CVS process running with the relevant process ID.

The only file stored in the CVS subdirectories in a repository is fileattr, which lists the file attributes of the files in the parent directory. The file attributes are settings for the cvs watch commands. In later versions of CVS, the fileattr file may be used for other attributes or the CVS subdirectory may be used for other files.

The format for fileattr is one line per attribute, each line containing information as follows:

                  entry-type 
                  filename (tab) attribute-name = attribute-value
 [;attribute-name = attribute-value...]

Attribute names starting with _ are reserved for CVS. Future versions of CVS may allow user-defined attributes. In the current version of CVS (version 1.11.5) and earlier, user-defined attributes are not allowed.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The CVSROOT directory contains administrative files that contain information about the projects stored in CVS. The CVSROOT directory can be checked out to a sandbox, edited, and committed in the same way as any other directories or files managed by CVS.

As part of the process of committing an administrative file, CVS exports a clear-text copy into the CVSROOT directory. The CVSROOT directory contains both RCS-format repository copies of administrative files and clear-text copies of the latest revision of the files. The RCS-format files are named filename,v. While CVS is creating the clear-text copies, it prints the message cvs commit: Rebuilding admnistrative file database.

Some of the files in CVSROOT allow you to run user-created scripts during the execution of CVS commands. Therefore, it's important to restrict the people authorized to commit or edit files in the CVSROOT directory.

It's good practice to have a specific username to own the CVSROOT directory and the repository root directory, and to be the initial owner of the CVSROOT files. This restricts the amount of damage that can be done to these files by a malicious or careless user, unless they happen to have root permissions.

Create a group to have the group ownership of the CVSROOT directory and files, and include only trusted people in that group. If this group should be permitted to create new projects, and consists of all the people who can, it can also own the repository root directory. The CVSROOT directory and most of the files should be writable only by the repository's owner and the group, but they must be readable by all users who will be running CVS commands. The directory's SGID bit should be set, to ensure that new files are created with the same group ownership as the directory.

Two files in the CVSROOT directory should be writeable by all the users who will be using the CVS commands: the history and val-tags files. These files may have a different group ownership than the rest of the files in this directory.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS reads some of the calling user's environment variables whenever you run a command for which the variable may affect the results. These variables, shown in the following list, are read and used by the process that runs on the repository's server. Note that these variables must be in the calling user's environment on the repository server, so different users may cause different behaviors.

In local-access mode, CVS uses both client and server environment variables.

CVS_SERVER_SLEEP: Delays the start of the client/server process by CVS_SERVER_SLEEP seconds to allow a debugger to be attached to it. Use this variable only when debugging the server in client/server mode.
CVSUMASK: Sets the default permissions of files in the repository. See Section 6.3 earlier in this chapter.

This variable may be added to the client code in a later version of CVS.
PATH: Locates any programs whose paths are not coded into the CVS program. It is also used for the programs called in the scripting files. The PATH variable is less important to CVS than it was when the rcs, diff, and patch programs CVS now uses were not included with CVS.
TMPDIR: Sets the temporary directory CVS stores data in. It defaults to /tmp. CVS creates temporary files with

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

A CVS repository can be backed up using the same backup tools and schedule that you use for ordinary text and binary files. You must be able to restore the repository with the same permissions and structure it had when it was backed up. You must restore the CVSROOT directory and its contents before the project directories are useful, but you can restore project root directories and their contents independently of each other.

If a file in a repository is being written to while a backup is in progress, it is possible that the file could be backed up in a state that might make it difficult for CVS to read it accurately when it is restored. For this reason, you should prevent processes from writing to the repository during a backup.

Freezing a repository is CVS-speak for the act of preventing users from changing the repository. The most common reason to freeze a repository is to ensure that a backup operation copies all the repository files in a consistent state.

The simplest way to freeze a repository is to block clients from accessing the CVS server. There are many ways to do this, such as shutting down the CVS server program, disallowing logins to the server system, blocking the server with a firewall rule, setting the server to single-user mode, or pulling out the network cable. Rather than blocking access to the server completely, you can use CVS's locks to read-lock the repository.

To keep the server running and allow clients to continue to read the repository files while a backup or other critical work takes place, use a script that creates lock files like CVS's internal locks. CVS honors these locks as if they were its own. Lock the directories you want to back up, make your backup, and then unlock the directories. See Section 6.4.2 in this chapter for a full explanation of CVS locks.

Example 6-7 shows a script that locks an entire repository. It attempts to lock the repository and backs off if it can't lock the whole repository. The backing off is necessary to prevent deadlocks. Example 6-8 shows a script that unlocks a repository.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

There are times when you need to restructure a project or when something has gone wrong in the repository. In an ideal world, restructures or repairs would all be done using the CVS commands explained in Chapter 3 or the cvs admin command explained in Chapter 7. Sometimes, however, those commands can't do what you're trying to achieve, and you need to modify the repository directly.

The main problem with editing the repository directly is that you may lose historic data. Removing files or directories affects retrieval of older releases of a project and may affect build scripts. Moving or renaming files or directories can affect older releases, build scripts, and instructions within your files.

Always freeze a repository with write locks before hand-editing it.

Always consider backing up and freezing the directories you're hand-editing. If you're just removing a stale lock, this isn't necessary. But you should backup and freeze directories if you're moving, removing, editing, or renaming content files. Try to get your users to commit and release their sandboxes before you hand-edit the repository. They can checkout new sandboxes afterwards.

If a user does not release an old sandbox and tries to act on a filename that the sandbox has records of, but the repository does not have the file, the user will receive strange errors. Correct these errors by releasing the user's sandbox copy of the file in question and then checking out the file again using the new filename.

If you are using the scripting files in the CVSROOT directory, you may need to edit them when a directory is moved or removed.

CVS does not have a built-in command for moving or renaming a file or directory. This doesn't mean that you can't move or rename files and directories; it just requires ingenuity.

To rename a file or directory, move it from the old name to the new name.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

A CVS sandbox is composed of a sandbox root directory, the project files and directories, and a special CVS subdirectory in the root directory and in every project directory. The sandbox root directory usually has the same name as the module it was created for, or it takes the name of the project root directory in the repository.

Project files in a sandbox are in editable form, just as if they were exported from the repository for release. The CVS subdirectory in each project directory stores metadata for the files in the project directory it is part of. This metadata is contained in a number of files (and one directory). Each of the sandbox directories may also contain a .cvsignore file.

Each project directory in a sandbox contains a subdirectory named CVS. This CVS subdirectory contains the files that store the administrative data for the files in the project directory. The following list describes the files and directories you will most likely find in a CVS directory. Files that are rarely encountered or are temporary are not included in this list. The full list of files is available in Chapter 11.

If you need to edit any of these files manually, back the file up before you start.

Base: Stores the pre-editing revision of any files that are being edited with cvs edit. This is a directory, not a file.
Baserev: Contains the revision information for every file in the Base directory, in the format name/revision/. Later versions of CVS may add to this format.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS reads the calling user's environment variables, described in the following list. The variables in the list are read and used by the process that runs on the client computer. Note that these variables must be in the calling user's environment, so different users may experience different behavior.

In local-access mode, CVS uses both client and server environment variables.

CVS_CLIENT_LOG: Used for debugging CVS in client/server mode. This variable should be set to a filename. If it is set, everything sent to the server is stored in the filename.in file and everything received by the client is stored in filename.out.
CVS_CLIENT_PORT: Used to set the port the client uses to connect to the CVS server in kserver, gserver, and pserver modes. By default, clients use port 2401 (gserver or pserver) or port 1999 (kserver) to connect to the server.
CVSIGNORE: A whitespace-separated list of filename patterns that should be ignored. See .cvsignore in the previous section.
CVSEDITOR or EDITOR or VISUAL: Used to set the editor CVS calls when it opens an editor for log messages. On Unix and Linux systems, this variable defaults to

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

You may at some point want to write a script that includes one or more CVS commands, such as a script to automatically export files from a repository to a web server, or a script to automatically update a test directory and attempt to build a program. If you do, you will need to know whether a given CVS command succeeded.

CVS commands set an exit status when they complete processing. A successful command always returns the success status. A failing command prints an error message and returns the failure status.

The cvs diff command behaves differently from the other commands. It returns success if it finds no differences and failure if it finds differences or encounters an error. This behavior may change in later versions of CVS.

Testing the exit status depends on the operating system. In Unix and Linux, the sh shell variable $? is 0 if CVS returns success, and nonzero if it returns a failure. Example 6-17 is a script to test a CVS return value.

Example 6-17. Testing return values

cvs commit -m "Automated commit"
if [ $? -eq 0 ]; then
        echo "Commit successful."
else
        echo "Commit failed with return code $?"
fi

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The team leader responsible for a project needs to know more about the project's tools than most other developers, or he needs to have a team member who knows about the tools. This chapter is for the team leader and the CVS specialist on the team. It concentrates on the files and directories that make up a project and how they are stored and managed in CVS, rather than on managing the development process itself.

The topics covered include initial creation of a project's CVS files, configuring a project as a module, exporting a project, integrating CVS with build systems and bug trackers, and configuring scripts to run when certain CVS commands are used.

This chapter also covers a special type of branch called a vendor branch, and concludes with a discussion of strategies and practices for using CVS that you may find helpful.

A project is any group of files and directories that exist beneath one project root directory. Every project must include at least one directory, because CVS needs to be able to create a subdirectory to store metadata about the project.

Most often, a project represents one program, one set of related configuration files, or one web site. Sometimes, a project is a collection of related items. For instance, I store all my articles for https://www.oreillynet.com/ in one project, with each topic grouped under a subdirectory. Sometimes a project is a subsection of something larger.

If you want to create a project right now with default settings and minimal reading, read Section 2.3 in Chapter 2. That section walks you through the process of importing a project.

To create a project in CVS, you need to have a copy of the files and directories you want to import, or an idea of which files and directories you want to make. You may modify this copy of the project, so make a copy in a temporary directory to use for importing.

If you have an existing set of files and directories, check whether you have files that can be generated from other files, such as compiled code. Files that can be generated easily do not usually need to be stored in CVS and can be removed from the copy of the project. It is good practice to store the commands that generate these files in CVS as part of the project, usually as a build script or as part of the installation document.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

A project is any group of files and directories that exist beneath one project root directory. Every project must include at least one directory, because CVS needs to be able to create a subdirectory to store metadata about the project.

Most often, a project represents one program, one set of related configuration files, or one web site. Sometimes, a project is a collection of related items. For instance, I store all my articles for https://www.oreillynet.com/ in one project, with each topic grouped under a subdirectory. Sometimes a project is a subsection of something larger.

If you want to create a project right now with default settings and minimal reading, read Section 2.3 in Chapter 2. That section walks you through the process of importing a project.

To create a project in CVS, you need to have a copy of the files and directories you want to import, or an idea of which files and directories you want to make. You may modify this copy of the project, so make a copy in a temporary directory to use for importing.

If you have an existing set of files and directories, check whether you have files that can be generated from other files, such as compiled code. Files that can be generated easily do not usually need to be stored in CVS and can be removed from the copy of the project. It is good practice to store the commands that generate these files in CVS as part of the project, usually as a build script or as part of the installation document.

If you have a set of files stored in another version control system and want to save their revision history, see Section 7.1.5 in this chapter. If you don't need to retain their revision history, export the files from the other system using a command that gives you a clean copy of the project with no administrative files, and use that copy to import from.

If you don't have any existing files, you can import a single directory with the project name. If you are more comfortable with a structure to work from, create an initial directory structure for your project and import that.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

All project leads need to distribute completed work at various stages of a project. When working with some projects, such as content management of web sites, you need to distribute files frequently with small changes. With others, such as large programming projects, you need to distribute files less often and with larger changes.

One way to distribute files is to use the cvs checkout command to produce a set of files for distribution. Another way is to use the cvs update command on an existing set of files.

The checkout and update commands are designed to produce a sandbox suitable for editing the files being checked out or updated. The commands create administrative files in the sandbox that most project leads don't want in a public distribution, so you may need to remove the administrative files in the CVS subdirectory from each of the checked-out directories.

There is a benefit to using checkout and update to distribute files. When you use either command on an existing sandbox, CVS sends only the differences between the revisions currently in the sandbox and the revisions requested from the repository. This uses less bandwidth than the export command, which retrieves entire files.

While cvs checkout creates a sandbox suitable for editing copies of a project's files, cvs export creates a release of the project's files that is suitable for publication. This command uses most of the same internal code as cvs checkout, but cvs export does not create any CVS subdirectories or CVS administrative files.

cvs export requires that you use a date or tag command option. The -D now or -r HEAD options export the latest revisions of all files in a project.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

In the repository's CVSROOT directory, there are several scripting files that allow you to run scripts while a project is being committed, tagged, updated, or modified in other ways. The scripts called from scripting files are often used to interact with other programs or to enforce standards.

Example 7-6 shows a commitinfo scripting file that runs a layout-testing program called indent-tester on the wizzard project files. CVS calls scripts in commitinfo before files are committed.

Example 7-6. Sample commitinfo file

^wizzard/src\(/\|$\) /var/lib/cvs/CVSROOT/indent-tester -gnu

When a project file is committed, CVS searches the commitinfo file for rules that match the project file's path; if CVS finds a rule, it runs the script given in that rule. The rule in Example 7-6 matches all files in the src directory (and its subdirectories) of the wizzard project and tells CVS to run the indent-tester script on those files. Later in this chapter, Example 7-8 shows the indent-tester script that can be used to enforce indentation standards for a project.

CVS processes the scripting files separately for each directory that is affected by a command, and it calls the script in the scripting file once for each directory it matches. If you run cvs commit wizzard, CVS checks commitinfo for patterns that match wizzard and runs the script once for the files in the wizzard directory, then does the same for each subdirectory, checking for patterns that match wizzard/doc and processing its files, followed by wizzard/lib and wizzard/src.

The scripting files are all stored in your repository's CVSROOT directory. The purpose of each file is described in the section of this chapter named for that file. Most of these files use a common syntax.

Some files don't use the common syntax. In such cases, the syntax is described in the same section as the file.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS is rarely used alone. There are a number of project-management tools available, each used to perform a different set of tasks. The scripting files can be used to connect CVS to other project-management tools, such as bug trackers and build scripts.

Interfacing with a bug tracker is easiest if the tracker accepts input from standard input or via an email form. Use the rcsinfo file to have the cvs commit editor screen include the template your bug tracker requires, and use the verifymsg file to ensure that all fields are filled in appropriately. Then have a script in verifymsg or loginfo mail the log data to your bug tracker.

Example 7-11 and Example 7-12 show how to integrate with the Bugzilla bug-tracking tool, available at https://bugzilla.mozilla.org/. These examples assume that the Bugzilla email gateway has been enabled. The @resolution field in the message template allows you to change a project's status and is supported directly by Bugzilla.

Use the verifymsg script in Example 7-11 to separate out the bug ID so it can be used in the mail subject (which must have the format [Bug XXXX]). The rest of the log message can be sent as the mail body. The script uses the read command to get the bug ID from the first line of the log message, checks that the first line it reads uses the format it expects, and then mails the bug ID and the rest of the stdin input to the user bugzilla on the same computer. The script returns 1 if the format was wrong and 0 if it succeeds in mailing everything to Bugzilla.

Example 7-11. Interfacing with Bugzilla, verifymsg

#! /bin/bash
read prompt bugid
if [ $prompt != '@bugid' ]; then
     return 1
else
     mail -s "[Bug $bugid]" bugzilla
fi
return 0

Example 7-12 shows an rcsinfo template file that contains the @bugid string that Example 7-11 expects and the @resolution

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Project administrators should be aware of the CVS commands described in Chapter 3 and Chapter 5. You may also want to read Chapter 4 and Chapter 6.

In addition to the commands described in those chapters, there are two commands that are particularly useful to project administrators: cvs admin and cvs history. cvs admin allows you to use RCS-like commands on files stored in the repository. cvs history provides a record of the actions performed on a project's files and is similar to cvs log or cvs annotate.

The cvs admin command is used to edit the RCS files directly in the repository. It is more accurately thought of as a set of commands than a single command, as it provides many of the commands that RCS would make available, though not all of these commands are usable or have an effect that matters to CVS. These commands are present mostly for historic reasons and backward compatibility with early versions of CVS.

If there is a system group called cvsadmin on the repository server, only users in that group can use the cvs admin command. If this group does not exist, any user can use the cvs admin commands on any repository files they have permission to change. Consider using the cvsadmin system group, as some of the cvs admin commands can prevent CVS from using the affected file or files.

There is a new option in the config file of CVS 1.12.1 and later. The UserAdminCommands option allows the system administrator to set cvs admin options that users who are not in the cvsadmin group can run.

The syntax for cvs admin is as follows:

cvs [cvs-options] admin command-options [filename...]

I strongly recommend always stating the filenames you wish cvs admin to act on, as some of the cvs admin commands can be difficult or impossible to recover from if you accidentally use them on the wrong file. If you do not specify a filename,

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS is a tool that can help you manage a project, but you need to decide how to use CVS with your project to make it work effectively for you and your team. The following sections present some ideas to help you integrate CVS into your working practices.

Decide whether and how you will use tags and branches, and then decide on the format to use for tag and branch names. Branching philosophies, styles, and policies are explained in Section 4.4 section of Chapter 4.

I strongly recommend keeping almost-complete work separate from experimental work. In programming projects, I recommend keeping bug fixes separated from the main body of development by putting either bug corrections or development on a branch.

If you use branches, designate an owner for each branch. The owner should be responsible for seeing that the branch is used for its specified purpose, for maintaining a record of the changes made to that branch, and for managing merges to or from that branch.

I strongly recommend tagging at strategic points in development, at the root of each branch, and at each merge point. See Section 4.1.6 of Chapter 4 for more suggestions for tagging.

Automation can be helpful in ensuring that a project moves smoothly to completion. Generally, automation translates into consistency. When using CVS on a project, you may find the following automation strategies to be helpful:

Use the scripting files in CVSROOT to enforce project standards and assist project communication.
Automate builds to encourage projects to be tested frequently. This also ensures that the entire build process is recorded and performed correctly every time.
Integrate CVS to your change-tracking program, to minimize the effort developers have to put in to do both version control and change tracking.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Most projects involve a repository on a different machine than the client. This chapter discusses remote repositories, access methods, how to set up each access method, and security considerations for each type of access.

This chapter also discusses the two access methods for local repositories: local and fork. fork represents a way to access a local repository as if it were a remote repository.

CVS can operate equally well as a single program that handles both the sandbox and the repository or as a pair of programs — a client managing the sandbox and a server managing the repository.

CVS can run as a single program if both sandbox and repository are on the same computer or if the repository is on a file server and the computer the sandbox is on perceives the shared directories as local.

If your file server or networking filesystem caches directory listings, the cached listings invalidate CVS file locking. Do not use caching filesystems with CVS.

If your file server or networking filesystem changes files in transit, the changes can corrupt the CVS data. This corruption can be subtle enough that it doesn't show up for weeks or months.

If you have a personal repository for private work, you may choose to keep the repository on the same computer as your sandbox. If you are sharing a mainframe with several other people, you may have a shared repository on the same mainframe as your sandboxes. In such situations, be particularly careful to back up the repository. When the repository and the sandbox are on different computers, each acts as a partial backup of the other. When they are on the same computer, that inherent backup is not available.

Whenever CVS runs a command from a client, it needs to know where to find the CVS repository. The address of the repository is called the repository path . CVS looks for repository paths in the sandbox, the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Whenever CVS runs a command from a client, it needs to know where to find the CVS repository. The address of the repository is called the repository path . CVS looks for repository paths in the sandbox, the CVSROOT environment variable, and the -d repository_path command option.

If you run a CVS command from within a sandbox, CVS uses the repository path that is stored in the sandbox. When a sandbox is not available — such as when you're creating a sandbox or issuing a command from outside a sandbox — you must specify which repository you are attempting to access. You also need to specify the repository path if you are in a sandbox but wish to access a different repository than the one the sandbox uses.

You can specify a repository path from the command line with the -d repository_path option, or you can specify it with the CVSROOT environment variable. CVS uses the path given with the -d option in preference to the path in the sandbox, and it uses either the sandbox or the -dpath in preference to the path in the environment variable.

The rtag, rlog, rdiff, rannotate, and export commands can run without a sandbox. If these commands are run outside a sandbox, they need either the -d option or the CVSROOT environment variable.

The format for a repository path is:

[:method:][[[user][:password]@]hostname[:[port]]]/path

The method can be one of the following:

local: For the local machine.
ext: For externally defined rsh or rsh-like connection methods (such as SSH).
fork

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

If your repository is on the same computer as your sandbox (or the sandbox you want to make) or on a shared filesystem that is accessed as if it were a local partition, you can use the localmethod to access the repository.

For the local access method, the repository path format is:

[:local:]/path

When running a command that requires an explicit path declaration, put the repository path in your CVSROOT environment variable or use the path as the argument to the -d repository_path option. You will most likely need this path declaration when creating a sandbox, but it is also necessary for cvs export and cvs rtag.

If you just enter the directory path with no hostname or method declaration, CVS uses the local access method.

With local access, CVS does not run in client/server mode. One program manages both the sandbox and the repository. The program runs under the username that it was called with, and it has the access permissions of that user. Any programs CVS calls (such as programs called from a scripting file) run with the same username and access permissions.

If local access mode is being used on a single-user computer, security normally is not an issue. On shared filesystems or mainframes, your repository security problems are the same as the usual security issues for file sharing. Use the security services of your operating system to secure a shared repository that is accessed with the local method.

Example 8-1 shows how to check out a sandbox using the local access method.

Example 8-1. Using the local access method

jenn@helit:/tmp$ cvs -d :local:/var/lib/cvs checkout wizzard
cvs checkout: Updating wizzard
U wizzard/Changelog
U wizzard/INSTALL
U wizzard/Makefile

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

In my experience, ext is the most commonly used access method, and it is usually used with SSH. ext stands for external, which refers to an external (to CVS) rsh or remote shell program. This method uses a remote shell program to connect the sandbox client computer to the repository server computer. The server method is almost the same as the ext method. The only difference is that server uses a remote shell program that is included with CVS.

To use a program other than rsh with the ext connection method, the CVS_RSH environment variable on the client should be set to the name of the program and the directory containing the program should be in the user's PATH on the client computer. Alternatively, you can set the CVS_RSH environment variable to the absolute path to the program, without modifying the PATH variable.

ext accepts any command line-based program that can be called with the following syntax:

program [-b] [-l username] host commands

The program must run the commands in a remote shell and pipe standard input (stdin) and standard output (stdout) without filtering the content. The -b is necessary only if the program is running on OS/2 and is used to force rsh to run in binary mode, without end-of-file conversion. The-l username is used (by CVS) only if there is a username included in the repository path.

For the ext access method, the repository path format is:

[:ext:][user@]hostname[:]/path

The user needs to have a username on both the client computer and the server computer. If these names are the same, the user@ part of the repository path isn't needed. In versions of CVS prior to 1.11.1, the colon between hostname and path was required.

Either the user's PATH environment variable on the server must include the directory that contains the cvs executable, or the user's

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The fork access method acts likeext without the external connection. You can use it only when the repository and the sandbox are on the same computer. fork makes CVS run in client/server mode and is most useful for debugging — to isolate whether a fault is in CVS's remote protocols or in the networking — but it is also used as a substitute for the local method.

The fork method uses the CVS_SERVER environment variable, as described in Section 8.3 earlier in this chapter.

The repository path format for fork is:

[:fork:]/path

With the fork access method, both client and server programs run under the username that the client was called with and have the filesystem access of that user. Any programs CVS calls (such as programs called from a scripting file) run with the same username and access.

Security normally is not an issue with the fork access method if the method is used on a single-user computer. However, be aware of the security issues of shared filesystems or shared mainframes; use the security services of your operating system to secure a shared repository that is accessed with the fork method.

Example 8-7 shows how to check out a sandbox using the fork access method.

Example 8-7. Using the fork access method

jenn@helit:/tmp$ cvs -d :fork:/var/lib/cvs checkout wizzard  
cvs server: Updating wizzard
U wizzard/Changelog
U wizzard/INSTALL
U wizzard/Makefile

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The gserver access method uses the GSS-API (Generic Security Service Application Programming Interface) to support authentication and encryption of the CVS connection. The GSS-API in itself does not authenticate or encrypt the connection; these processes are performed by an authentication or encryption system configured to work with the GSS-API. The most common system used with the GSS-API is Kerberos 5.

The GSS-API is explained in RFC 2743, available at https://www.ietf.org/rfc/rfc2743.txt. RFC 1964 explains how the GSS-API interacts with Kerberos 5. To use Kerberos 5 with CVS, use the GSS-API and the gserver access method. Kerberos 4 is used with the kserver access mode, explained in the next section.

The repository path format for the GSS-API is:

:gserver:[user@]hostname[:[port]]/path

The default port for gserver is 2401. If user is not specified, the client sends the username of the calling user on the client computer.

The CVS client and server must both be compiled to run the GSS-API. If you intend to encrypt the data stream, you also need to have encryption enabled at compile time. You can test whether your CVS program has the GSS-API compiled by attempting to check out a sandbox. Example 8-8 shows the result when CVS does not support the GSS-API.

Example 8-8. Testing for gserver mode

bash-2.05a$ cvs -d :gserver:cvs:/var/lib/cvs checkout wizzard
cvs checkout: CVSROOT is set for a GSS-API access method but your
cvs checkout: CVS executable doesn't support it.
cvs [checkout aborted]: Bad CVSROOT: `:gserver:cvs:/var/lib/cvs'.

You can test for encryption support by checking the options list, as shown in Example 8-9.

Example 8-9. Checking for encryption

bash-2.05a$ cvs --help-options 
CVS global options (specified before the command name) are:
.
.
.
    -x           Encrypt all net traffic.
.
.
.
(Specify the --help option for a list of other help options)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The kserver method is used to connect using Kerberos 4. If you do not have an existing Kerberos 4 installation on your CVS repository server, I recommend you use Kerberos 5. Kerberos 4 has known weaknesses that Kerberos 5 resolves. This section assumes that you have an existing Kerberos 4 installation and the documentation to configure and use it.

Kerberos 4 is a reasonably secure authentication system, but it has known flaws. Kerberos 5 fixes some of them; most critically, it prevents a replay attack. In Kerberos 4, there is a five-minute window in which an attacker can sniff an authentication request, modify and re-send it, and get an authentication ticket. Kerberos 5 allows only one ticket to be produced per request.

The repository path format for Kerberos is:

:kserver:[user@]hostname[:[port]]/path

The default port for kserver is 1999. If user is not specified, the client sends the username of the calling user on the client computer.

The CVS client and server must both be compiled to run Kerberos 4. If you intend to encrypt the data stream, you also need to have encryption enabled at compile time. You can test whether your CVS program has compiled kserver support by checking the command list, as shown in Example 8-11.

Example 8-11. Testing for kserver mode

bash-2.05a$ cvs --help-commands
CVS commands are:
.
.
.
        kserver      Kerberos server mode
.
.
.
(Specify the --help option for a list of other help options)

You can test for encryption support by checking the options list, as shown earlier in Example 8-9.

To use CVS with kserver, install and configure Kerberos 4 as described in your Kerberos manual. You need to have the header files for Kerberos 4 available for CVS to link to. The principal name for CVS is cvs.

To recompile CVS to support Kerberos 4, follow the instructions in Chapter 2 on installing from source. Use the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The pserver method allows users to connect to the repository with a username and password that are stored on the repository server. The main advantage of pserver is that it permits anonymous, passwordless, read-only access. The main disadvantages of pserver mode are that it uses a trivial encoding scheme for passwords and the data stream is not encrypted. pserver mode is included in CVS automatically, but it requires a password file that needs to be configured.

To use pserver, you need a username on the repository computer, to enable CVS to run programs on that computer. You may share this username (your system username) with other users and have a separate CVS username to identify you to CVS as an individual. You also need to log in before running other commands.

To support the pserver access method, CVS needs to run a server on the computer that hosts the repository. To configure the repository to run the CVS server, edit inetd.conf and add cvs pserver. See Section 8.8 of this chapter for more information on inetd configuration.

The repository path format for pserver is:

:pserver:[[user][:password]@][hostname:[port]]/path

The default port for pserver is 2401. If the user is not specified, the client sends the username of the calling user on the client computer.

You need to configure the passwd file and possibly the readers and writers files before you can use pserver. These files are explained in Section 8.7.1 and Section 8.7.2 of this chapter. You also need to use the login command, explained in Section 8.7.3 .

You can bypass the passwd file by using the SystemAuth configuration option in the config file (explained in Chapter 6).

If you bypass the passwd file using SystemAuth, CVS uses the shell account passwords for your users with the minimal security it uses for pserver passwords. Be sure you take the security risks into account if you choose to do this.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

gserver , kserver , and pserver access modes require a server to run on the repository computer. For these modes, the server is started with inetd or xinetd . inetd is configured in the "Other services" section of /etc/inetd.conf, as shown in Example 8-18 and Example 8-19. Note that the configuration must be all on one line.

Example 8-18. Inetd for gserver and pserver

#:OTHER: Other services
2401 stream tcp nowait root /usr/bin/cvs cvs -f --allow-root=/var/lib/cvs pserver

Example 8-19. Inetd for kserver

#:OTHER: Other services
1999 stream tcp nowait root /usr/bin/cvs cvs -f --allow-root=/var/lib/cvsroot kserver

The gserver access method connects to a pserver CVS server. The code that runs the server end of pserver checks whether it has been connected to with the pserver or gserver access method and runs the appropriate server code.

The parameter to the --allow-root option is the path to the repository root directory. If there will be several different repository root directories, add more --allow-root options.

You can use the -T option or the TMPDIR environment variable to set a specific temporary directory. If no directory is listed, /tmpis used.

It can be useful to run the server as a special user, possibly named cvs, to limit the amount of damage that can be done if one of the arbitrary scripts (or CVS itself) is insecure. If you do this, ensure that the repository root directory and the CVSROOT files start out being owned by the cvs user, and make sure that the cvs user is in all the groups that can use the repository. You also need to ensure that all users run as user cvs, perhaps by having that as the system username in pserver access mode.

If CVS has root privileges, it runs the scripts called from the scripting files as the user who calls CVS, not the user named in

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

It would be nice if CVS were perfect, but it isn't. There will be times when CVS doesn't work as expected, but with the techniques and information in this chapter, you should be able to fix the most common problems.

Most of the CVS error messages are helpful but concise. They usually tell you what is wrong and may contain key words or phrases that lead you toward a resolution to the problem. Few of the error messages actually provide a resolution, however, because usually there are several possible causes of any given problem.

If your problem seems to be confined to a single sandbox, the simplest solution is usually to check out a new sandbox. To save changed files, copy them to the new sandbox before erasing the old sandbox. (If the new sandbox has newer revisions of some files, don't copy over them.)

To fix problems in a single sandbox directory, check the sandbox administrative files in the CVS subdirectory. If a command has been aborted, the administrative files may have been partially changed. Chapter 6 explains the sandbox administrative files.

Many repository problems are caused by permissions errors. If a user can't read the repository and the problem doesn't seem to be a networking issue, check the repository permissions. Thankfully, permissions problems are easy to fix. Chapter 6 covers permissions in detail.

CVS is an open source software program, created by a group of programmers rather than a specific company. Because there is no company that created CVS — which means there is no company that gains revenue from selling it — there is no official source of commercial support. If you want commercial support, there are companies in many parts of the world that provide high-quality support for open source products. CVS is a widely used version control system, so most of these companies have staff who are familiar with CVS.

Section 9.1.1.1: Mail and newsgroups

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Most of the CVS error messages are helpful but concise. They usually tell you what is wrong and may contain key words or phrases that lead you toward a resolution to the problem. Few of the error messages actually provide a resolution, however, because usually there are several possible causes of any given problem.

If your problem seems to be confined to a single sandbox, the simplest solution is usually to check out a new sandbox. To save changed files, copy them to the new sandbox before erasing the old sandbox. (If the new sandbox has newer revisions of some files, don't copy over them.)

To fix problems in a single sandbox directory, check the sandbox administrative files in the CVS subdirectory. If a command has been aborted, the administrative files may have been partially changed. Chapter 6 explains the sandbox administrative files.

Many repository problems are caused by permissions errors. If a user can't read the repository and the problem doesn't seem to be a networking issue, check the repository permissions. Thankfully, permissions problems are easy to fix. Chapter 6 covers permissions in detail.

CVS is an open source software program, created by a group of programmers rather than a specific company. Because there is no company that created CVS — which means there is no company that gains revenue from selling it — there is no official source of commercial support. If you want commercial support, there are companies in many parts of the world that provide high-quality support for open source products. CVS is a widely used version control system, so most of these companies have staff who are familiar with CVS.

Section 9.1.1.1: Mail and newsgroups

There are also sources of help on the Internet, such as mailing lists and newsgroups. These are meeting places for people who are familiar with CVS, and for those who need help with it.

The official mailing list is monitored by several CVS developers. Subscribe to the list at

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

If you are having difficulty connecting to a repository, first check that the repository path is declared correctly. The most common mistake when checking out a new sandbox is to forget to specify the repository path at all. Another common mistake is to forget to specify the connection method if you are using a method other than local or ext.

If you want to examine the data sent to or received from the server, set the CVS_CLIENT_LOG environment variable to a file name. It must be set on the client computer, and the traffic is logged in files in the current working directory named for that filename, with the suffixes .in and .out. For instance, if you set CVS_CLIENT_LOG to cvslog, the traffic is logged to cvslog.in and cvslog.out. (Traffic to the server is logged to cvslog.in, and traffic from the server is logged tocvslog.out.)

The gserver, kserver, and pserver connection methods rely on a server that is started with inetd. inetd sets a limit on the number of connections per unit of time and delays further connections. If you expect heavy use of CVS, you may need to configure inetd to accept more connections per minute. Not doing so may cause connection refused error messages.

If you are in an active sandbox and are receiving an error like the one shown in Example 9-2, the Root or Repository file in the CVS subdirectory of the current sandbox directory has become unreadable. Chapter 6 includes an explanation of these files and what they should contain, but the simplest way to correct a problem in a sandbox is to remove and recreate the sandbox. If there are changes in the sandbox files, be sure to preserve them before removing the sandbox.

Example 9-2. Repository undeclared

cvs update: No CVSROOT specified!  Please use the `-d' option
cvs [update aborted]: or set the CVSROOT environment variable.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS reserves some filenames for its own uses, and other filenames are included in the default ignore list.

If you have a file that CVS appears to be ignoring, check the default ignore list and any cvsignore files in your repository, home directory, or sandbox. The default list is provided in Section 6.5.3.2 of Chapter 6. If the -I! option to a CVS command causes CVS to recognize the file, then you can be sure the file is in a cvsignore list. You can temporarily force CVS to recognize an ignored file by stating it explicitly as a command parameter.

CVS uses CVS and Attic directories in the repository. CVS prevents you from using the filename CVS but permits you to create files or directories called Attic. If you use an Attic directory and look in the repository, the Attic directory has files that don't exist on the trunk from the directory above it, as well as those you are currently using in your sandbox version of the Attic. You should avoid using Attic as a file or directory name.

CVS may ignore a filename with a # or .# prefix, as CVS reserves some files with the prefix .# for its own use. In the sandbox, CVS uses the .# prefix for copies of files it has overwritten during a merge. In the repository, lock files start with #.

Another cause of filename problems is a conflict between the filesystem on a client computer and the filesystem on a repository. For example, filename case is significant in Linux and Unix filesystems, but not in Windows filesystems. If two filenames vary only in case and you are checking them out to a filesystem that ignores case, the second file to be checked out may overwrite the first. This can also cause problems when you attempt to change the case of a file in Windows. Another possible, case-related problem is that if you are disconnected from the network, on an operating system that doesn't consider case relevant, then you cvsremove FiLe and try to cvs add file, CVS may search the pending requests, see that

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

If CVS is reporting lines as longer or shorter than they should be, there may be a problem with the line-ending conversion from one filesystem to another.

If you are using the ext access method with an rsh replacement, your replacement may be trying to convert line endings. CVS relies on being able to do the conversion itself.

If this is not the problem and the file in question is a text file, you might have binary keyword-expansion mode set for the file. Use the command cvs status filename to show the keyword-expansion mode, and use cvs admin -kkv filename to fix the file in the repository by setting its keyword-expansion mode to the default for text files. If a binary file is corrupted, it might be set as a text file. The command cvs admin -kb filename sets the binary file's keyword-expansion mode correctly, but it might not repair the damage to the local file. To retrieve the original version of the file, use cvs update -r 1.1 -p > filename.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

For all access methods except pserver, CVS relies exclusively on the filesystem to manage permissions. Each user must have a username on the repository server, and must have write access to every directory that contains files they will need to commit.

You can control permissions only at a directory level. If a user will need to commit to any file in a directory, she needs read and write access to the whole directory.

Once, I was working on a project where I had to connect to the repository server through an intermediate proxy server. We kept getting permission errors and eventually tracked it to the intermediary. We all had membership in the col group on the client and repository servers, but not on the intermediary. As files passed through the intermediate server, their group membership information was lost, so they were saved in the repository with no group ownership. We corrected this by setting the repository directories' SGID flags on the repository server.

The history and val-tags files in the repository's CVSROOT directory must be writable to all CVS users. The history file can be removed if none of your users use the cvs history command.

The pserver connection method uses a more complicated permission system than the one other connection methods use. The passwd file in the repository's CVSROOT directory can cause a user to have two effective usernames: one that affects only CVS and another that affects the filesystem. If a user has permission within one but not the other, he may be unable to access his project files. For instance, if his CVS username is in the writers file in the CVSROOT directory, CVS attempts to allow him to write to his project files. If, however, his system username is not allowed to write to the project directories, the operating system denies access and CVS is unable to write to the files.

The readers and writers files in the repository's

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS removes its lock files when a CVS process completes properly, but processes that are killed can sometimes leave lock files in place. Chapter 6 explains the process of removing lock files and provides an example of the messages CVS displays when a lock file is present.

If you have to wait for valid lock files frequently, you may need to reduce the length of time a lock file is active in the repository. Locks are based on the directory that is being locked, so if you have frequently accessed project directories with many files or large files, you may benefit from splitting them into smaller directories.

If you are waiting for lock files frequently, you can also check whether your system is being overloaded. You may have network trouble, or large checkouts or commits may be overloading your system memory or swap space.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

This chapter is a comprehensive reference of all CVS commands, with a brief summary of what each does. It is intended to be useful as a quick reference, not a tutorial.

If you have never used CVS before, I suggest you read Chapter 2 or Chapter 3 before reading this reference. Those chapters explain the basic concepts of CVS and how to use it effectively.

CVS supports a number of command-line options that you can use to control various aspects of CVS behavior. Command-specific options are described in Section 10.2, later in this chapter. This section focuses on options that you pass to the cvs executable itself, not to any specific CVS command.

The syntax of any CVS command is as follows:

cvs [cvs-options] [command] [command-options-and-arguments]

The cvs-options modify the behavior of the main CVS code, rather than the code for a specific command. The following options are valid:

-a: Authenticate all network traffic. Without this option, the initial connection for the command is authenticated, but later traffic along the same data stream is assumed to be from the same source.

This option is available only with GSS-API connections, but if you use ssh as your rsh replacement in the ext connection mode, ssh authenticates the data stream.

This option is supported if it is listed in cvs --help-options. The command-line client can be compiled to support it by using the --enable-client option to the configure script.
--allow-root=directory: Used as part of the inetd command string for server, kserver, and pserver connection methods. The directory is the repository root directory that the server allows connections to. Using --allow-root more than once in a command allows users to connect to any of the specified repositories.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS supports a number of command-line options that you can use to control various aspects of CVS behavior. Command-specific options are described in Section 10.2, later in this chapter. This section focuses on options that you pass to the cvs executable itself, not to any specific CVS command.

The syntax of any CVS command is as follows:

cvs [cvs-options] [command] [command-options-and-arguments]

The cvs-options modify the behavior of the main CVS code, rather than the code for a specific command. The following options are valid:

-a: Authenticate all network traffic. Without this option, the initial connection for the command is authenticated, but later traffic along the same data stream is assumed to be from the same source.

This option is available only with GSS-API connections, but if you use ssh as your rsh replacement in the ext connection mode, ssh authenticates the data stream.

This option is supported if it is listed in cvs --help-options. The command-line client can be compiled to support it by using the --enable-client option to the configure script.
--allow-root=directory: Used as part of the inetd command string for server, kserver, and pserver connection methods. The directory is the repository root directory that the server allows connections to. Using --allow-root more than once in a command allows users to connect to any of the specified repositories.
-b=directory: Exists for backward compatibility with old versions of CVS and does nothing in current versions. It used to specify the directory for the RCS executables.
-d repository_path

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Most of your interaction with CVS is through the various CVS commands. Even if you use a graphical client, most of the functions the client uses call the CVS commands.

Most commands have a shortened nickname that you can type instead of the longer command name. These are called command synonyms in CVS jargon.

add

Synonyms: ad, new

cvs [cvs-options] add [-k mode] [-m message] files

Adds a file or directory to the repository. This command can also be used to undo an uncommitted file deletion or to restore a deleted file. Remember, you must commit any added files in order for the addition to fully take effect.

Command options

-k mode: Add a file or files with the designated keyword-expansion mode. This option also sets the default keyword mode for the file. If you forget to set the default keyword mode with cvs add, you can do so later with cvs admin.

The keyword-expansion modes are listed in Section 11.6 of Chapter 11.
-m message: Use the specified message as the description of the newly added file. The description is shown in cvs log output.

Example

bash-2.05a$ cvs add Design.rtf 
cvs server: scheduling file `Design.rtf' for addition
cvs server: use 'cvs commit' to add this file permanently

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

This chapter is a comprehensive reference of CVS topics other than commands. It is intended to be useful as a quick reference, not a tutorial.

If you have never used CVS before, I suggest you read Chapter 2 and Chapter 3 before reading this reference. Those chapters explain the basic concepts of CVS and how to use it effectively.

This chapter contains the following sections:

Section 11.1: Describes CVS administrative files in the sandbox on the client computer or in the user's home directory on the server.
Section 11.2: Describes CVS administrative files in the repository's CVSROOT directory.
Section 11.3: Describes variables you can use in the administrative files in the CVSROOT directory.
Section 11.4: Describes date and time formats you can use with CVS.
Section 11.5: Describes environment variables on the server or the client that affect CVS.
Section 11.6: Describes the keywords CVS uses, the expansion modes that affect how CVS processes the keywords, and how CVS processes line endings.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Each sandbox directory has administrative files in its CVS subdirectory, but it may also have hidden files in the directory itself, with filenames that start with a dot (.). The user's home directory can contain CVS administrative files that affect all of that user's sandboxes; these filenames are also prefixed with a dot.

In client/server mode, all the dot files other than .rhosts should be on the client computer. The .rhosts file should be in the user's home directory on the server computer.

These are the dot files in the sandbox directory:

.cvsignore: Contains a list of files CVS should not process. This file uses the same format as cvsignore in the repository's CVSROOT directory and may be checked into CVS.
.#filename.revision: If a project file that is not fully synchronized with the repository is overwritten by CVS, the original file is stored as.#filename.revision, where revision is the BASE revision of the file.

These are the dot files in a user's home directories:

.cvsrc: Contains a list of CVS commands and the options the user wants as default options for those commands.
.cvsignore

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The CVSROOT directory in the CVS repository contains several administrative files. Most of these files are editable by the user and are stored in both RCS format (with a ,v suffix) and plain text to be used by CVS. These files can be checked out and committed like any other CVS file.

The history and val-tags files should not be edited. The passwd file should never be checked out; it should be edited in place.

The checkoutlist file is used to designate files to be stored in the CVSROOT directory in both RCS and clear-text formats. Most of the CVS administrative files are stored this way automatically, and the checkoutlist file allows you to store user-created files in the same way. The most common files to be stored like this are scripts executed by the scripting files (commitinfo, loginfo, rcsinfo, taginfo, and verifymsg).

The file format is to simply list the names of the files, one file per line. All files must be in the CVSROOT directory.

The commitinfo file defines programs to run before a file is committed. If any of the programs exit with a nonzero exit status, the commit does not proceed. These programs run on the repository computer.

The file syntax is as follows:

                  name_pattern 
                  action

The name_pattern is a regular expression that must match a relative path within the repository. The action is a command-line template or the address of a script, plus any parameters required for that script or template. The full path of the repository and the filenames of all files to be committed are appended as parameters by CVS during processing.

Example 11-1 shows a commitinfo file that calls a

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The administrative files in CVSROOT can use several types of variables: internal, environment, and shell variables. You can use these variables to pass parameters to the scripts in the scripting files, or you can use them as part of command-line templates.

The internal variables allow you to use information CVS stores about the currently running command. The environment variables are used to access information from the environment the command is running in, and the shell variables are used to access information about the shell.

Three environment variables are set when CVS runs commands or scripts from CVS administrative files:

CVS_USER: This variable is meaningful only with the pserver access method. It refers to the CVS username provided in the leftmost field of the appropriate line in CVSROOT/passwd. If this username does not exist, the variable expands to an empty string.
LOGNAME and USER: Both of these variables contain the username of the user calling the CVS process.

In the pserver access method, the username is the third field of the line in passwd. If no username is there, the CVS_USER value is used.

The syntax for referencing a CVS internal variable is ${VARIABLE}. The $VARIABLE syntax can also be used if the character immediately following the variable is neither alphanumeric nor an underscore (_).

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

In CVS, all dates and times are processed by a version of the GNU getdate function, which can translate dates and times given in several different formats. Case is always irrelevant when interpreting dates. Spaces are permitted in date strings, but in the command-line client a string with spaces should be surrounded by quotes. If the year is 0 to 99, it is considered to be in the twentieth century.

If a time is not given, midnight at the start of the date is assumed. If a time zone is not specified, the date is interpreted as being in the client's local time zone.

The legal time and date formats for CVS are defined by the ISO 8601 standard and RFC 822 as amended by RFC 1123. Other formats can be interpreted, but CVS is designed to handle only these standards.

Section 11.4.1.1: ISO 8601

The basic ISO 8601 date format is as follows:

                     year-month-day 
                     hours:minutes:seconds

All values are numbers with leading zeros to ensure that the correct number of digits are used. Hours are given in 24-hour time. This produces the structure YYYY-MM-DD HH:MM:SS, which is internationally acceptable and can be sorted easily. You can use a date, a time, or both.

If you're using ISO 8601 format with the hyphens, the full date is required in CVS. The YYYYMMDD date format is also acceptable and can be abbreviated to YYYYMM or YYYY.

The HH and HH:MM time formats are acceptable. Times can also be specified without the colon, so HHMMSS or HHMM are usable.

Be aware that HHMM may be misinterpreted as YYYY. Get into the habit of using separators.

In strict ISO 8601 format, a T is required between the date and the time, but CVS understands this format with or without the T. The ISO 8601 standard also states that a Z at the end of the string designates UTC (Universal Coordinated Time), but CVS does not recognize the use of

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Several environment variables affect CVS. Some are read only when CVS is the client, and some are read only when CVS is the server. In local or fork modes, both sets are read.

The environment variables in the following list are read and used by the process that runs on the client computer and must be in the calling user's environment:

COMSPEC: OS/2 only. This variable sets the command interpreter and defaults to CMD.EXE.
CVS_CLIENT_LOG: Used for debugging CVS in client/server mode. If set, everything sent to the server is stored in the CVS_CLIENT_LOG.in file, and everything received by the client is stored in CVS_CLIENT_LOG.out.
CVS_CLIENT_PORT: Used to set the port the client uses to connect to the CVS server in kserver, gserver, and pserver modes. By default, the client uses port 2401 (gserver and pserver) or port 1999 (kserver) to connect to the server.
CVSIGNORE: A whitespace-separated list of filename patterns that should be ignored. See Section 11.2.4 earlier in this chapter.
CVS_IGNORE_REMOTE_ROOT: Obsolete since CVS 1.10. When set, it prevented CVS from overwriting the CVS/Root file if the -d repository_path option was set. CVS no longer overwrites the file.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS contains keywords that can be included in nonbinary project files. When CVS finds a keyword in a file it is checking out, it expands the keyword to provide metadata about the latest revision of the file. You can set keyword-expansion modes on a file to tell CVS whether (and how) to expand the keywords it finds.

Keyword-expansion modes also control line-ending conversion. Unix, Macintosh, and Windows operating systems use different sets of codes to signal the ends of lines. (Linux uses the same codes as Unix.) When you commit a file from an operating system that doesn't use Unix line endings, CVS converts the line endings to Unix style. If you are storing binary files, this conversion can corrupt the file. Use the -kb keyword-expansion mode to tell CVS not to convert line endings.

CVS keywords take the form:

$Keyword$

All keywords except Log expand to the format:

$Keyword: value$

These are the keywords and the information they show about the file they are in:

Author: The username of the user who committed the last revision.
Date: The date on which the last revision was committed, in UTC.
Header: A header containing information about the file, including the author, date and revision number, path and filename of the RCS file (project file in the repository), file status, and whether the file is locked. See Chapter 5 for information about file locking.
Id: A header like the one given by the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS uses two different forms of pattern matching, depending on which aspect of CVS is attempting to match the pattern. Most CVS functions use sh-style wildcards, but the scripting files in the CVSROOT directory use regular expressions.

This section is not a comprehensive study of regular expressions or wildcards. For a more complete discussion of regular expressions, I recommend Mastering Regular Expressions (O'Reilly) by Jeffrey E. F. Friedl.

Wildcards are used by most CVS functions, including wrappers and ignore files. The wildcards are evaluated by a version of the fnmatch standard function library distributed with CVS.

The wildcards are sh-style, and the symbols used in CVS include:

?

Matches any single character.

\

Escapes the special symbols, so they can be used as literals.

*

Matches any string, including the empty string.

[ ]

Matches any one of the enclosed characters. Within the brackets, the following symbols are used:

! or ^: If either of these characters is the first character after the open bracket, the brackets match anything that is not included in the brackets.

char1-char2

Denotes the range of characters between

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS provides a variety of ways to access the repository. These methods are briefly described in the following sections, and Chapter 8 explains them in more detail.

On the client side, you specify the access method as part of the repository path. If you don't declare one of the following methods, CVS assumes either the local or ext method:

local: Connect to a repository on the same computer as the sandbox, but do not use client/server mode.
ext: Connect with an externally defined rsh or rsh-like connection method (such as ssh). If you use anything other than rsh, the CVS_RSH environment variable must be set on the client computer.
fork: Connect to a repository on the same computer as the sandbox as if it were a remote machine. This method is useful if you are trying to diagnose problems with client/server mode.
gserver: Connect to the repository using the GSS-API and Kerberos 5.
kserver: Connect to the repository using Kerberos 4.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

While some people like using the command line during development, others prefer graphical interfaces. Graphical user interfaces (GUIs) also use colors and shapes to make output clearer or make the sandbox easier to work with.

Graphical CVS interfaces are available for Windows, Macintosh, and Unix or Linux systems, and there are also two Java graphical interfaces that run on any operating system with a Java Runtime Environment. These GUIs were written by third-party developers and do not come with CVS.

Third-party developers have also written tools to interface between CVS and several of the common integrated development environments (IDEs). These interfaces are most useful to programmers and are available for Microsoft Developer Studio, MetroWerks CodeWarrior, NetBeans, GNU Emacs, and anything that uses the SCC-API (Common Source Code Control Application Programming Interface). IDEs that support the SCC-API include Macromedia ColdFusion, Sybase PowerBuilder, and Microsoft Visual Studio.

CVS is designed for the Unix and Linux operating systems, and it relies on the features of those operating systems. It can behave in unexpected ways when used from a different operating system. The most obvious problem is that Windows operating systems use a different character for line endings than Unix-based systems do. CVS corrects for that particular problem, but other problems are explained in this appendix.

Section A.1: Multi-Operating-System Clients

Section A.2: Macintosh Clients

Section A.3: Unix and Linux Clients

Section A.4: Windows Clients

Section A.5: Integration Tools

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

If your development team is not familiar with CVS, you may want to ensure that everyone is using the same CVS client. This helps minimize support problems; if someone has a problem, his fellow developers are familiar with the tools he's using and can offer helpful advice.

The clients described in this section look and operate the same across several different environments. The first three represent a set of clients that are designed for all three major operating systems—Unix/Linux, Macintosh, and Windows—and work from the same base code. The other two GUI clients are Java clients that work on any operating system twith a Java Runtime Environment.

Three GUI clients—gCVS, MacCVS, and WinCVS—represent a set of clients available from the same development team that work identically across Unix/Linux, Macintosh, and Windows operating systems. The clients are detailed and implement most of the functions available from the CVS command line. Using these clients, you can create a new repository, tag files, create watches, and report on the differences between files. These clients are available from https://www.wincvs.org and https://cvsgui.sourceforge.net/.

gCVS is for Linux and Unix, WinCVS is for Windows, and MacCVS is for Macintosh. Because their interfaces are so similar, these are good clients for groups that develop software across different operating systems.

These clients are laid out with three main windows, as shown in Figure A-1 (gCVS) and Figure A-2 (WinCVS). The leftmost window contains a directory tree, the base directory of which is configurable. The upper-right window shows the contents of the current directory, and the lower-right window shows the output of the CVS commands that you execute using the GUI.

Figure A-1: The gCVS main window

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

There are three clients available specifically for the Macintosh operating system: MacCVS (described earlier in Section A.1), MacCVSClient, and MacCVS Pro.

If you are running Mac OS 9 or earlier, you need to be aware of two issues:

The Macintosh CVS clients for OS 9 and earlier don't have built-in SSH support. You can use SSH by following the tunnel workaround in Section A.1.1.3.
CVS clients in Mac OS 9 and earlier may have line-ending issues, as described in Section A.4.

OS X does not have either of these problems, as it has a built-in SSH client and both OS X and CVS use Unix-style line endings.

If you are running OS X, in addition to using the Macintosh-specific clients mentioned in this chapter, you can use the CVS command-line client, as well as the Unix and Linux graphical clients.

The Concurrent Versions Librarian (CVL) client is designed specifically for Mac OS X. It is available from https://sente.epfl.ch/software/cvl/.

MacCVSClient is available for OS X and earlier versions from https://www.heilancoo.net/MacCVSClient/.

The main display of MacCVSClient is a modules window, which provides a hierarchical list of files that includes status information. Output from commands such as diff or log is stored and can be retrieved from this window later in the session, as well as immediately after you run a command. If you switch to another application, then return, MacCVSClient attempts to refresh the cached states and modification times of any open folders.

MacCVSClient supports the pserver and ext (rsh-only) repository-access methods. You can configure the repository path in the Preferences dialog from the Edit menu, shown in Figure A-6. Conflicts and the results of the diff command are color-coded to improve readability.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS is native to the Unix and Linux operating systems; consequently, there are no line-ending or capitalization issues. The standard, command-line client is intended for use with Unix and Linux, but there is also a wide variety of graphical CVS clients available for Unix and Linux systems.

Cervisia is available from https://cervisia.sourceforge.net/. It requires the QT and KDE libraries, but it runs on Gnome and other graphical environments if the QT and KDE libraries are available.

Cervisia provides a configurable list of frequently used CVS repositories, and configurable key bindings for common commands. Cervisia supports the commit, import, and updatecommands, as well as the tagging and watching sets of commands. One particularly useful setting is the option to run cvs edit automatically, to notify other developers when you intend to edit a file.

Cervisia has two main sections in its display screen, shown in Figure A-8. The upper section lists files and directories, and the lower section displays the output of the CVS commands that Cervisia executes for you. Right-click on a file in the upper section to open a menu with options to open the file in an editor, commit a changed file, add a file, remove a file, or run a diff over two revisions of a file.

Figure A-8: The Cervisia CVS client

The Resolve menu option, which you can access by right-clicking the mouse, supports automatic conflict resolution. When you invoke automatic conflict resolution, Cervisia displays both files, as well as the merged version of the two files. Cervisia then allows you to choose from several methods for handling any conflicts as a result of the merge.

LinCVS is available from

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

There are two graphical CVS clients available specifically for Windows. One is WinCVS, which is described in Section A.1 of this chapter. The other is TortoiseCVS, which modifies the way Windows Explorer presents files.

Following are some issues you might encounter when using CVS from Windows. These issues apply equally to WinCVS and TortoiseCVS.

Line endings differ between Windows and Unix

CVS automatically attempts to convert the line endings of text files to Unix format. This is helpful in text files, but it causes problems in binary files that are committed accidentally as text files. When a binary file is corrupted because CVS tried to "fix" the line endings, often you can recover with the following procedure:

Back up the current sandbox copy of the file.
Update the file with cvs update to bring the repository version into the sandbox and reconvert the line endings.
Check the file to ensure that it is no longer corrupt. If it is still corrupt, roll back to the most recent uncorrupted version (hopefully, the backup).
Use cvs admin -kb filename to convert the default keyword-expansion mode of the file to binary.
Recommit the file to the repository with cvs commit -f.

SSH may attempt to convert line endings

Because CVS performs its own line-ending conversion, you cannot use an SSH client that converts line endings as the client for CVS.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Developers rarely use CVS in isolation. The tools described in this section coordinate CVS with other programs. Some integrate CVS into IDEs; others are used in separate windows but ensure CVS can manage an IDE's files properly.

abCVS is a plugin for CodeWarrior that allows you to use CVS without leaving the CodeWarrior IDE. It requires CodeWarrior and a command-line CVS implementation such as CVSNT (explained in Appendix B). The developers of abCVS also recommend that you have a CVS client such as WinCVS.

abCVS implements the update, commit, add, remove, edit, log, status, and diff commands. Most commands can run on a single file, or they can run recursively down a directory tree. abCVS is still in an early stage of development.

abCVS is available from https://www.iaanus.com/abCVS/.

Anjuta is an IDE for the Linux and Unix operating systems that relies on the Gnome libraries. It supports more than a dozen languages (including C/C++, Java, Python, Perl, and ADA) and provides an integrated debugging facility, syntax highlighting, context-sensitive help, and support for autoconf and automake.

Anjuta provides simple, clean access to CVS commands on files in CVS sandboxes, including an intuitive interface to cvs diff. Anjuta is available from https://anjuta.org/.

BBEdit is an HTML and text editor for the Macintosh. Version 7 for OS X includes an integrated CVS client that supports multiple repositories. BBEdit is available from https://www.barebones.com/products/bbedit.html.

CVSIn is an add-in for Microsoft Developer Studio that integrates Microsoft Developer Studio and WinCVS. It permits most simple CVS commands to operate directly from Microsoft Developer Studio and relies on WinCVS for more complex CVS commands and commands that operate on directories rather than individual files.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS is an open source program, and all the information necessary to interface to it or change it is freely available. It is also a very popular system. The combination of these two factors means that a wide variety of programs and tools have been written for CVS.

The tools in this appendix range from a port of CVS to the Windows NT operating system, to a small tool to mail log messages automatically. Other programs include several different viewers to display the contents of the repository with an HTTP server and a useful program that implements access-control lists.

Section B.1: CVS Variants

Section B.2: Distribution Tools

Section B.3: Logging Tools

Section B.4: Metadata Tools

Section B.5: Convertors

Section B.6: Miscellaneous

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The CVS license allows you to modify the CVS code and distribute the modified code. Several variants are provided by developers who have produced expansions of CVS for specific purposes.

CVS/MVS is a port of CVS for the MVS (Multiple Virtual Storage) mainframe operating system, also known as OS/390 and zOS. CVS/MVS requires MVS with POSIX configured, and the HFS (Heirarchical File System).

CVS/MVS is a port of both the server and the command-line client.

CVS/MVS is available at https://cvsmvs.dccmn.com/.

CVSNT is an alternative CVS server for Windows NT and later, Unix, and Linux. It includes a command-line client as well as the server, and the client can be used with some of the integration tools described in Appendix A.

As well as running on Windows operating systems, CVSNT provides an additional access method, sspi, that authenticates using NT domain passwords. It also allows you to lock branches to specific developers and has a Windows-style installation script. However, CVSROOT scripts that rely on a Unix-like shell environment may not work under CVSNT.

CVSNT is available at https://www.cvsnt.org.

Meta-CVS is an expansion of CVS that adds versioning for directories, supports symbolic links and file metadata, automatically sets the keyword-expansion mode for certain file types (such as .png files) to binary, and improves the user interface for branching and merging. It also improves the way CVS handles file addition and removal conflicts and changes the way vendor branches are used.

Meta-CVS is a variation of the client code and operates from a standard CVS repository. It changes the data stored in the repository, so you can't have a team on the same project with a mixture of Meta-CVS and standard CVS users.

Meta-CVS is available from

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Often, you may want to develop a CVS project and publish the files for display or download. You can publish the resulting files with a build script or a script in one of the CVSROOT files. Alternatively, you can use one of the tools in this section, all of which display CVS project files.

Some of the tools in this section display the repository; others export files from the repository for publication. Some retrieve the difference between the revision they have and the latest revision in the repository, then patch the revision they have and display the final files.

Chora provides the ability to view or download the files in a CVS repository using a web browser. It integrates with the other web tools available at https://www.horde.org. The CVS integration is stored in a single library, so you can customize the rest of the display.

In file mode, every revision of a file is displayed along with log messages and you also have the ability to display the differences between revisions. File mode also offers a color-coded branch view.

Chora is available from https://www.horde.org/chora/.

CVSup is a tool for distributing files across a network. It can be used with most file types and understands CVS project files. If desired, it can use zlib compression to reduce network load.

If CVSup is working from CVS files, it distributes the differences rather than the files as a whole, saving bandwidth and minimizing the network load. It also understands tags and distributes specific tagged versions if configured to do so.

CVSup is available from https://www.cvsup.org.

This tool publishes CVS files using FTP. It was developed for web sites that use CVS for content management, but for which the administrator of the server requires that updates be made using the FTP protocol.

CVSviaFTP does not start an FTP session automatically; it needs to be wrapped in a script that manages login and other specifics of your FTP site. However, it is useful when you are managing content across an FTP link.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

CVS log messages often contain useful information for project managers, programmers, and other CVS users. There are many tools that manipulate log messages, including tools to create a change log automatically, mail log messages, and change the format of log messages. These tools are most useful if you and your development team enter meaningful log messages.

CHalogen is a change-log generator that relies on the CVS project files being tagged at each significant stage of the project. It generates a change log that displays the changes between tag points. The generated change log is in HTML format.

CHalogen can run as a CGIscript or from the command line.

CHalogen is available from https://www.softwarebee.de/products/chalogen/.

clmerge is a script that merges conflicts in a GNU-style change log. The change log is sent to the standard output, so the script output should usually be redirected to a file. This script is useful as a postprocessor to change log generation programs.

clmerge is available from the contrib directory in the CVS source code.

These scripts are designed to work together. commit_prep ensures that the Id keyword is present in the file and checks the version number of the keyword. It prevents older revisions from being copied into the sandbox and replacing an existing revision. It also records information for log_accum .

log_accum consolidates the log messages from a single commit of multiple directories and mails the resulting consolidated log messages — including a consolidated list of which files were added, removed, and modified — to a specified address.

These scripts should be called from the scripting files in the CVSROOT directory.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The tools described in this section provide metadata about the CVS project files or use existing file metadata to provide additional functionality. Using these tools, you can search your log comments or your repository, see a graph showing the rate of file accesses over the past week, or find out who changed which files most recently.

CVS Monitor is a specialized CVS client that displays module and file information, graphic summaries of user activity within modules, change logs, file histories, and other information. It runs as a CGI script and presents its output in a web browser.

CVS Monitor is available from https://ali.as/devel/cvsmonitor/.

CVSPlot is a Perl script that plots statistics from a CVS project, such as the number of lines of data or the number of files in a module. It generates the results as a text file or as a .png graph that models the change over time.

CVSPlot is called from the command line and can be used in a script. It allows you to specify the period of time and the file types you are interested in. It requires Perl, and to plot graphically it also requires gnuplot.

CVSPlot is available from https://cvsstat.sourceforge.net/.

CVSSearch runs keyword searches on the comments stored as a result of file commits. Its output includes not only every comment that contains keywords you specify, but also filenames and links to the code that matches the comment.

Recent versions of CVSSearch allow you to search your code as well as your log comments. CVSSearch requires a web server and operates as CGI code.

CVSSearch is available from https://cvssearch.sourceforge.net/.

These scripts display the status of project files. cvsstat shows which files have been modified locally, which files have been modified in the repository by other users, and which files are up-to-date.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

If you want to use CVS with a project that is currently being stored in a version control system other than CVS, you need to convert the files from the other system to CVS. Fortunately, scripts to do just that are available on the Internet and in the CVS source distribution.

The rcs-to-cvs script checks RCS files in to CVS. It also checks in files that didn't previously have source control. It starts by checking whether the current directory's subdirectories exist in the repository; then it commits the files. Files that do not already exist in the repository are checked in as revision 1.1.

rcs-to-cvs is available from the contrib directory in the CVS source code.

These scripts convert between RCS and SCCS version control. Note that rcs2sccs supports only one level of branching. Both scripts retain as much of the file metadata as possible.

rcs2sccs and sccs2rcs are available from the contrib directory in the CVS source code.

VSS2CVS is a Perl script to synchronize Visual Source Safe and CVS repositories. It is intended to convert from one source control system to the other and may need modification if you want to try to use both systems simultaneously.

VSS2CVS runs on Windows machines and requires a Perl interpreter (such as ActivePerl) and two utilities that are available with Cygwin.

VSS2CVS is available from https://www.laine.org/cvs/vss2cvs/.

pvcs2rcs reads files from Merant PVCS version control and writes a copy of those files using RCS version control. It acts recursively and leaves the PVCS archive unchanged.

pvcs2rcs is available from the contrib directory in the CVS source code.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The tools described in this section are too unique to be categorized easily. However, they are very useful. They range from a tool to clear out old data from the history file, to a tool to mount the repository as a filesystem.

This script removes most of the old records from the history file in the CVSROOT directory in the repository. It keeps records of file modification, addition, and removal, keeps the last change to each tag, and removes everything else. This effectively compresses the history file by removing most of the outdated data.

cln_hist is available from the contrib directory in the CVS source code.

This script implements access-control lists within CVS. It must be the only script in the commitinfo file in the CVSROOT directory and should be set as DEFAULT so it is called by all files. The script permits access control based on the username, project directories, and branches within the projects.

cvs_acls is available from the contrib directory in the CVS source code.

CVSCheck provides status information for files in the current sandbox. Its output is more concise than the output of cvs status or cvs log, so it's a handy tool for checking status in large sandbox directories.

CVSCheck is available from the contrib directory in the CVS source code.

CVSFS is a tool for mounting a CVS repository as a filesystem. It works only with the pserver access method (as of CVS 1.1.9). By default, it displays the current (HEAD) revision of the trunk of any file. Its main use is reading a repository, and it can be useful as a build tool.

CVSFS is available from https://sourceforge.net/projects/cvsfs/

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Synchronization Commands

File Commands

Branch Commands

Tag Commands

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Use the following syntax to issue CVS commands:

cvs [cvs-options] command 
[cmd-options] [args]

Replace cvs-options with one or more of the following:

-a: Authenticate the data stream
--allow-root=directory: Set the repository root directory (used in server modes)
-d repository-path: Specify the repository path for the current command
-e editor: Use the specified editor in commit or import commands
-f: Do not use the ~/.cvsrc file
-H or --help: Display help for CVS
--help-commands: Display a list of CVS commands
--help-options: Display a list of CVS options
--help-synonyms: Display a list of synonyms for CVS commands
--H command or --help command: Display the options and help for the specified command
-l

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Repository path format is as follows:

            [:method:][[[user][:password]@]
hostname[:[port]]]/path

Access methods can be any of the following:

ext: Connection through external rsh or rsh-like program
fork: Client/server mode on local computer
gserver: Connection through the GSS-API and Kerberos 5
local: Local computer, no client/server mode
pserver: Connection through password server
kserver: Connection through Kerberos 4
server: Connection through internal rsh server

Key environment variables relating to repository access are:

CVS_RSH: Specifies rsh-like executable
CVSROOT: Specifies repository path

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The following lists show the syntax to use in performing common CVS tasks. Remember that for any CVS command you can specify the repository path using the -d option. For example:

cvs -d repository_path checkout
project

For brevity, the -d option is not shown in any of the example commands. However, it can be added to any of the commands.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Create a new sandbox

            cvs checkout project

Remove a sandbox

            cvs release directory

Check out files as of a specific tag name or revision

            cvs checkout -r [tagname|revision] 
project

Check out files as of a specific date or time

            cvs checkout -D [date|time] project

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Upload changes to the repository

            cvs commit [filenames]

Force upload of unchanged files

            cvs commit -f [filenames]

Download changes from the repository

            cvs update [filenames]

Download changes, and download new directories

            cvs update -d [filenames]

Download changes, but not empty directories

            cvs update -P [filenames]

Download changes and clear sticky revision, date, keyword mode, or branch

            cvs update -A [filenames]

Convert an existing sandbox to a specific tag name or revision

            cvs update -r [tagname|revision] 
project

Convert an existing sandbox to a specific date or time

            cvs update -D [date|time] project

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Add new files or directories to the repository

            cvs add [filenames]

Add new binary files to the repository

            cvs add -kb [filenames]

Remove files or directories from the repository

            cvs remove [filenames]

Remove files or directories and delete from the sandbox

            cvs remove -f [filenames]

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Create a branch from within a sandbox

            cvs tag -b branchname [filenames]

Create a branch from anywhere using a tag name or revision

            cvs rtag -r [tagname|revision]
-b branchname project

Create a branch from anywhere using a date or time

            cvs rtag -D [date|time] branchname project

Check out a branch sandbox

            cvs checkout -r branchname  
project

Convert an existing sandbox to a branch sandbox

            cvs update -r branchname [filenames]

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Tag files from within a sandbox

            cvs tag tagname [filenames]

Tag files from anywhere using a tag name or revision

            cvs rtag -r 
[existing_tagname|revision] 
new_tagname project

Tag files from anywhere using a date or time

            cvs rtag -D [date|time] tagname project

Move a tag from within a sandbox

            cvs tag -F tagname [filenames]

Move a tag from anywhere using a tag name or revision

            cvs rtag -r 
[tagname_at_location|revision] -F 
tagname_to_move project

Move a tag from anywhere using a date or time

            cvs rtag -D [date|time] -F tagname project

Delete a tag from within a sandbox

            cvs tag -d tagname [filenames]

Delete a tag from anywhere

            cvs rtag -d tagname project

The -r [tagname|revision] option accepts a tag name or a revision, but cannot have both tag name and revision. The -D [date|time] option accepts a date, a time, or both date and time.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Table of Contents

Section 4.4.1.1: Basically stable

Section 9.1.1.1: Mail and newsgroups

Section 9.1.1.1: Mail and newsgroups

Section 11.4.1.1: ISO 8601