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
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.
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):
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.
You can avoid calling an editor at all by using the -m message command option. This option is available with add, commit, and import.