Essential CVS (Essentials)

2017-07-07 02:10:07

A sandbox is a local copy of a project's files, used to make changes and test work. Each developer should work from her own sandbox on a computer that is convenient to 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.

3.2.1 Permissions and Ownership

Files lose their permissions when they are transferred to the repository. CVS normally will check 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.

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.

Group ownership of files in the repository is important, because CVS prevents users from checking out files they do not have read access to. Chapter 6 explains ownership and security issues with CVS.

If the ownership of, and permissions on, files is 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 in the -d command option when you check out the sandbox. CVS stores the repository path in the sandbox.

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

[: method :][[[ 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 will use 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 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. ^[2]

^[2] 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 will not need to use the repository path for that sandbox again.

Section 3.2 earlier in this chapter discusses accessing repositories.

If you expect to use a repository for many sandboxes, 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. CVS keeps administrative files in this subdirectory, including the Root file that contains the address of the repository the sandbox came from. The Repository file contains the module name, if applicable , or the path from Root to reach the contents of the directory.

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.

Example 3-2. Using cvs checkout

bash-2.05a$ ls cvsbook linuxchix newsforge oreilly bash-2.05a$ cvs -d cvs:/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

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. 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.4 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 actually is more work than the first way. It also means that some of the CVS history tracking may be lost.

3.2.5 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 need to be stored in binary mode, 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 stored in binary mode.

If you are producing an image or some other nontext file, add the file to CVS as a binary file, as explained in Section 3.6 later in this chapter.

Top