3.2. Sandboxes and Repositories
A sandbox is a local copy of a project's files, used to make changes and to test work. Each developer should work from her own sandbox on a computer that is convenient for 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. CVS maintains this subdirectory itself, and it is extremely rare for users to need to edit it.
Two commands keep your sandbox synchronized with the repository: cvs update and cvs commit. An update brings changes from the repository to the sandbox, and a commit sends changes from the sandbox to the repository. See Figure 3-2 and the sections "Committing Changes to the Repository" and "Updating the Sandbox Files from the Repository" later in this chapter.
Figure 3-2. Updating and committing
3.2.1. Permissions and Ownership
Files lose their permissions when they are transferred to the repository. CVS normally checks 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 within the sandbox.
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.
This setup would normally cause problems, but CVS relies on the Unix feature called groups, which is also used on Mac OS X and Linux. A group of users can have group ownership of a file, and CVS will allow any member of the group to access the file and download it to his sandbox. Chapter 6 explains ownership and security issues with CVS in more detail (in this paragraph, I have oversimplified the issue).
If the ownership of files and permissions on files are important to your project, you should set them in build and installation scripts. This issue usually affects projects that are installed for production use. Chapter 7 discusses this topic in more detail.
3.2.2. Repository Paths
When you create a sandbox, you need to specify the repository to which it is connected. You do this by setting the repository path, either by putting it in the CVSROOT environment variable on your client computer, or by declaring it with the -d command option when you check out the sandbox. CVS stores the repository path in the sandbox.
The repository path is the path CVS uses to find the repository. The general format for repository path is:
Each access method (method in the syntax) has a slightly different syntax. Chapter 8 provides the correct syntax for each method.
These are the access methods:
Everything except the path itself may be left out of a repository path definition.
If the method is left out but the host is included, CVS uses either the server or the ext method, depending on whether an internal RSH server is available. If both the host and the method are left out, CVS uses the local access method.
If user is left out, CVS uses the current, operating-system login username. If password is left out but is required, CVS asks for it.
Chapter 8 explains repository connection methods.
3.2.3. Browsing the Repository
CVS 1.12.8 introduced a pair of wonderful new commands. These commands allow you to browse the repository as if it were your local filesystem. Both the repository and the client must be 1.12.8 or later.
The commands are cvs ls and cvs rls. Without a parameter, the commands display the contents of the repository equivalent of the local directory (cvs ls), or the repository root directory (cvs rls). Parameters can be filenames or paths, and should be relative to the default directory the command displays. You must provide a repository path with cvs rls.
3.2.4. Creating a Sandbox
The cvs checkout command is used to create a sandbox. Once the sandbox is created, checkout no longer needs to be used in that sandbox; update is the preferred command from that point. However, checkout may be called in a sandbox, in which case it is similar to update -d.[*]
checkout is called with the names of files, directories, or modules in the repository. A module is a collection of files and directories under one root directory that has been given a module name. Chapter 7 explains modules.
The syntax of cvs checkout is:
cvs [cvs-options] checkout [command-options] project
You must provide the path to the repository that contains the module or directory. This can be done with the CVSROOT environment variable on the client machine, or with the -d repository_path CVS option. If your repository is on a local machine, the repository path is the full path of your CVS repository's root directory. If your repository is on a remote machine, contact your system administrator and request the path for the repository. Once you have created a sandbox, you do not need to specify the repository path for that sandbox again, because it is stored in the CVS subdirectory.
"Sandboxes and Repositories," earlier in this chapter, discusses accessing repositories.
checkout creates a new directory in the current working directory. By default, this directory has the name of the module, file, or directory being checked out.
checkout creates a CVS subdirectory in every directory of the sandbox. The CVS subdirectory was described in the earlier section "Sandboxes and Repositories," and is further described in Chapter 6.
The following command options are commonly used with cvs checkout and can also be used with cvs update:
Example 3-2 shows the wizzard project being checked out of a CVS repository. Figure 3-3 shows the dialog window for the same checkout, from the graphic CVS client Cervisia. The Checkout option is under the Repository menu in Cervisia.
Example 3-2. Using cvs checkout
Figure 3-3. Using cvs checkout with Cervisia
The need to retrieve a list of the projects stored in the CVS repository is common. The command cvs -d repository_path checkout -c provides a list of the modules registered in the modules file in the repository. Unfortunately, this command lists only modules and does not include files and directories that are not part of a module. If you have CVS 1.12.8 or later, you can use the new cvs rls command to find the ones which aren't modules. Modules are explained in Chapter 7.
The command cvs -d repository_path checkout downloads everything in the repository, which usually is not what you desire. If you have direct access to the repository, listing the root directory of the repository provides a full list of project root directories. Combining this with the list of modules from checkout -c provides a complete list of projects.
3.2.5. Checking Out from Multiple Repositories
CVS permits you to check out directories from multiple repositories into the same sandbox directory. You do this by creating the sandbox with checkout, as normal, then changing directory into the sandbox and checking out other sandbox directories from within the first. When you use a recursive command from the top directory of the sandbox, CVS will use the correct repository for each subdirectory.
Versions of CVS prior to 1.10 do not handle this properlyupdate to a modern version of CVS if you intend to use multiple repositories within the one sandbox.
3.2.6. Changing Repositories
There are two ways to switch the repository that a sandbox is checked out from:
3.2.7. Editing Sandbox Files
Once files are in your sandbox, you can edit them normally. For files saved as text, use your favorite text editor.
If you intend to produce text but prefer an editor that provides page and style formatting, be aware that files from editors that save in a nontext file format must be flagged as binary, which prevents some of CVS's most useful functions from working. File formats such as RTF, TeX, XML, HTML, and LaTeX are text-based and can be used with CVS without needing to be flagged as binary.
If you are producing an image or some other nontext file, these must also be added to the repository as a binary file, as explained in "Adding Files to the Repository" later in this chapter.