Section 3.1. General Information

3.1. General Information

CVS stores project data in a repository, but you don't work directly from the repository. As mentioned earlier, 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 any number of subdirectories. Every subdirectory contains a special CVS directory, with metadata files.

A typical CVS session would involve the developer updating a sandbox with the latest versions from the repository, editing the files and making changes, perhaps running a build script and testing changes, and then committing those changes to the repository.

When you are ready to test or install your project, use the export command, as explained in Chapter 7. 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 script can include the necessary export commands if desired. The sandbox is a place for making changes; it's not a place for running the project.

3.1.1. Lock Files

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 while the changes are being committed to the repository. (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 directorythat is, that CVS is in the act of committing the other developer's changes. Depending on the size of the files being changed, and the speed of the network, this process can take as little as a fraction of a second, or as long as 10 minutes. In my experience, it takes CVS less than a second to make text changes on a local LAN, or a minute or two to process a large image file across a dial-up network.

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, including how to determine whether the lock is valid.

3.1.2. CVS Command Syntax

CVS commands follow this syntax:

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

The cvs-options modify the behavior of CVS as a whole, and their functions include help, quiet operation, changing the default editor, and changing the CVS root directory.

All the commands have aliases, which are short versions of the command. For example, cvs commit can be run as cvs ci. The aliases are in the reference section of this book, and are listed with the command cvs help-synonyms.

The command-options modify the command's behavior and can change which parts of the sandbox, or which revisions in the repository, a command will operate on.

Here are the cvs-options (left-side options) that you will use most often (see Chapter 10 for a full list):

-H or help

Displays information about the CVS command but does not execute it.

-Q or -q

Suppresses informational messages. -q is quiet; -Q is very quiet and prints only warnings.

-d repository_path

Tells CVS which repository to use to run the command on.

-e editor

Changes the editor that CVS calls when prompting for messages.

-n

Does not change any files. This option is useful when trying to figure out what a command does without risking damage to the repository or the sandbox.

-z compression_level

Compresses the file transfer over a network.

In this book, the command-options (right-side options) are discussed with their commands. Full lists of each set of options are available in Chapter 10.

At the command line, documentation for the CVS options is available with cvs help-options. Command options for each command are available with cvs -H command. The list of all available CVS commands is available with cvs help-commands.

3.1.3. Choosing Your Editor

In Unix, Linux, and Mac OS X, CVS invokes the vi editor by default when asking for log messages. There are several ways you can change the default editor. Chapter 10 has a more extensive discussion of Unix editors.

CVS checks the command line, the .cvsrc file, or your environment variables to see whether you have set an editor. You can use any of the following options to set an editor. These options are in order; the earliest option takes precedence.

1. Call CVS with the -e editor option.

2. Set the cvs -e editor line in your .cvsrc file on the client machine.

3. Set the environment variables CVSEDITOR, EDITOR, or VISUAL on the client machine as the calling user. CVSEDITOR is preferred and overrides EDITOR and VISUAL.

You can avoid calling an editor at all by using the -m message command option. This option is available with add, commit, and import.