Section 3.2. Sandboxes and Repositories

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.

We Couldn't Get Our Files!

This is another tale of CVS ignorance from my past. My colleagues and I were working on a project, and were connecting to one machine (call it bechamel) from our workstations, because it had the necessary build tools and testing tools. So our sandboxes were on bechamel. Our repository was on another machine (call it caramel), but to get from bechamel to caramel, we had to go through a tunnel via a third machine. The network admin set it up for us and ensured that we had access to the repository.

However, neither we nor the network admin fully understood CVS security. He ensured that the group existed on both bechamel and caramel. We ensured that our files were set with read-write-execute for the group, in our sandboxes on bechamel, then added them to the repository on caramelbut our fellow group members didn't receive the files when they updated.

When we investigated the repository, we found that they'd lost the group membership. I still don't know why. But we fixed it anyway: by setting the SGID bit in the repository's project directories, we ensured that the correct group ownership and permission was set for all files in the directory. In fact, I've been doing that ever since, and have never had a recurrence of the problem.

The quickstart guide and Chapter 6 explain how to set the SGID bit.

The repository path is the path CVS uses to find the repository. The general format for repository path is:

 [:method[;option=arg]:][[[user][:password]@]hostname[:[port]]]/path 

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:

local

Connect to the local machine.

ext

Connect using an externally defined rsh or rsh-like connection method (such as ssh).

server

Connect using the internal rsh server (available only on some operating systems).

pserver

Connect using the pserver (password server) connection method.

gserver

Connect through the GSS-API (currently used for Kerberos 5.0).

kserver

Connect through Kerberos 4 and earlier.

fork

Connect to a local machine as if it were a remote machine, using pipes for communication (useful if you are trying to diagnose problems).

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 similar to update -d if it is called from the directory in the sandbox that corresponds to the project parameter given to checkout. If it is called from a different directory, it checks out a new sandbox based in the current working directory.

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 

cvs checkout directory and cvs checkout directory/ are identical. However, cvs checkout module and cvs checkout directory/ are different, unless the module happens to refer to a directory of the same name at the root level in the repository.

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.

If you expect to use a repository for many sandboxes on the same machine, specify its path using the CVSROOT environment variable. If you expect to use it only for one sandbox, use the -d CVS option.

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:

-P

Prunes empty directories.

-D date or -r revision or -r tag

Checks out a specific revision of the module based on date, revision, or tag.

-f

Forces CVS to check out the latest revision of a file if the date specified with -D doesn't match any date of the file or if the revision specified by -r doesn't match any revision of the file. -f is useful only with -D or -r. Use this option carefully, as it can cause confusion.

-j revision or -j revision1 -j revision2

Merges revisions. With one -j, CVS merges the changes between a common ancestor and the specified revision into the current sandbox. The common ancestor is the most recent revision that predates both the specified revision (found in the repository) and the sandbox revision.

With two revisions specified, CVS determines the differences between revision1 and revision2 and then merges those changes into the sandbox.

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

 bash-2.05a$ ls cvsbook   linuxchix  newsforge   oreilly bash-2.05a$ cvs -d cvs_server:/var/lib/cvs checkout wizzard cvs server: Updating wizzard U wizzard/Changelog U wizzard/INSTALL U wizzard/Makefile U wizzard/README U wizzard/TODO cvs server: Updating wizzard/doc cvs server: Updating wizzard/lib cvs server: Updating wizzard/man cvs server: Updating wizzard/src U wizzard/src/main.c U wizzard/src/wizzard.h bash-2.05a$ ls cvsbook    linuxchix  newsforge  oreilly  wizzard bash-2.05a$ ls wizzard Changelog  CVS     doc  INSTALL  lib  Makefile  man  README  src  TODO 

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:

• The official, recommended way is to commit all changes, use cvs release to release the sandbox, delete the sandbox, then check out a new sandbox from the new repository.

• The other way is to edit CVS/Root in all the directories in the sandbox. Unless you have only one directory, this way actually is more work than the first approach. It also means that some of the CVS history tracking may be lost.

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.