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.
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.
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.
CVS commands follow the 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.
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 of CVS options.
Displays information about the CVS command, but does not execute it.
Suppresses informational messages. -q is quiet; -Q is very quiet and only prints warnings.
Tells CVS which repository to use to run the command on.
Changes the editor CVS calls when prompting for messages.
Does not change any files. This is useful when trying to figure out what a command does, without risking damage to the repository or the sandbox.
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.
In Unix and Linux, CVS calls the vi editor by default when asking for log messages. There are several ways you can change the default editor.
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.
Call CVS with the -e editor option.
Set the cvs -e editor line in your .cvsrc file on the client machine.
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.