Inhaltsverzeichnis von Essential CVS

Inhaltsvorschau

CVS is a version tracking system. It maintains records of files throughout their development, allows retrieval of any stored version of a file, and supports production of multiple versions of a file. CVS enables multiple developers to work simultaneously on a single file without loss of data. Each developer works on her own copy of a file, and all changes are later merged into a single master copy. CVS can be integrated with bug-tracking and feature-tracking systems, and it provides features that can assist a project manager by tracking changes to a project over time.

CVS can be used in many environments for many purposes: maintaining configuration files, mail aliases, source code, FAQ files, art, music, articles, essays, and books. Some system administrators keep the contents of their /etc directory under CVS in order to track system configuration changes over time. CVS is also used to store and automatically publish content to web sites and FTP servers.

CVS follows the Unix ethos of small programs doing what they do well. The RCS (Revision Control System) program handles revision control of single files, so CVS uses RCS to store file data. CVS adds features to RCS—most notably, the abilities to work on collections of files and to work out of a repository that may be local or remote.

Version control is the process of recording and being able to retrieve changes to a project. Computer scientists define version control, source control, and change management as different but overlapping tasks; version control is the most accurate term for the aspects of the field that apply to CVS. A version control system lets you retrieve an old version to fix bugs or update features, to branch development to allow the project to progress along multiple tracks simultaneously, and to generate reports that show the differences between any two arbitrary stages of a project.

Most version control systems store notes with each change, and many provide tools that allow a project leader to analyze the changes. Most also include the ability to retrieve differences between arbitrary versions of files, which makes it easier to create patches or locate bugs.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Version control is the process of recording and being able to retrieve changes to a project. Computer scientists define version control, source control, and change management as different but overlapping tasks; version control is the most accurate term for the aspects of the field that apply to CVS. A version control system lets you retrieve an old version to fix bugs or update features, to branch development to allow the project to progress along multiple tracks simultaneously, and to generate reports that show the differences between any two arbitrary stages of a project.

Most version control systems store notes with each change, and many provide tools that allow a project leader to analyze the changes. Most also include the ability to retrieve differences between arbitrary versions of files, which makes it easier to create patches or locate bugs.

The benefits of a version control system such as CVS include:

Any stored revision of a file can be retrieved, viewed, and changed.
The differences between any two revisions can be displayed.
Patches can be created automatically.
Multiple developers can work simultaneously on the same project or file without overwriting one another's changes.
The project can be branched to allow simultaneous development along varied tracks. These branches can be merged back into the main line of development.
Distributed development is supported across large or small networks. (CVS offers a variety of authentication mechanisms.)

Using version control for a project requires some extra work on an ongoing basis. In addition, previous versions of files, or records of changes to the various files in a project, occupy disk space that you might otherwise use for something else. However, the features that a good version control system makes available are well worth the investment of time and disk space. For example, without version control, project backups typically are timestamped copies of an entire project, hopefully stored together in a logical fashion. Version control provides organized storage and retrieval of the complete record of project changes, rather than whichever copies someone might remember to make.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

With all the version control systems available, why choose CVS? If you work with files that change over time, the most important thing is to have some kind of version control: after the first time it's saved your bacon, you'll never want to work without it. If it's your first time with a version control system, choose one with good documentation and the features you think you'll need for the first year or two. Read the available tutorials and quickstart guides, and use a system that you feel you can understand. As you're already taking a look at this book, CVS is a fine choice: it will get you through that first year or two, and beyond.

Any version control is better than no version control.

Once you're used to working with version control, you can make a more informed decision about the features you'll want long term, and choose a system with those features in mind. Changing systems is not something to fear, as there are tools for conversion between many version control systems. At worst, you can use one system for the old data and another for the new, or write a script that checks out each revision in turn from the old system and commits it to the new.

Every version control system that I'm familiar with records the changes in a document, enables you to retrieve older versions of the document, and enables you to display the differences between versions. (The first two features are what defines a version control system.) Some systems do little more than that, but most have additional features. You should choose a system based on the features that are most important to your project and working style.

One of the most important features a version control system can provide is support for multiple developers. There are two common models for this support; choose the model that works best for you. The easiest to understand is exclusive development: the version control system permits only one developer at a time to work on any individual file. A system may have strict exclusive development and make it nearly impossible for a developer to work on a file he hasn't reserved, or it may have advisory exclusive development and simply warn the developer before allowing access to a file that another developer is editing. The alternative to exclusive development is

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS records file changes during a project's development. Project files are added to the repository as they are created, and developers check out a personal sandbox—a personal copy of the project's files—to work from. Each developer works in his own sandbox and regularly commits his changes to the repository. Developers also update the contents of their sandboxes regularly to ensure that changes to the repository are reflected in each sandbox.

The term project can take on many different meanings. The stereotypical CVS project is a programming project in which files contain source code for the various programs written as part of the project. But that's a narrow view of what a CVS project can be. CVS can be used in many other settings as well, as the next few sections demonstrate.

CVS can store configuration files, mail aliases, domain records, and other files for which changes should be tracked. Import the files (or all of /etc) into a repository and require administrators to check them out into a sandbox to make changes. Commit the files back to the repository and export the changes to the server. If the changes fail, rolling back to the previous state is easy.

Multiple servers with varied but similar configurations can be maintained using different branches of the same files. Changes to any given branch can be merged into other branches selectively.

Every change made through CVS is recorded in a file history, along with the username of the person making the change, the date the change was made, and any notes recorded with the change. All this information can help, for example, when trying to spot which change to which configuration file broke the mail server.

Both the CVS server and the client run on all Unix and Linux operating systems, including modern Macintosh environments. Third-party graphical clients are available for Unix, Linux, Windows, and Macintosh systems, and for the Java runtime environment. The CVSNT CVS server is available for Windows NT or later. This makes CVS particularly useful for cross-platform environments. See Appendix A for more information.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

To help you get up to speed quickly using CVS, this chapter explains the most common CVS operations. The commands and examples in this chapter are based on standard situations and cover only the most common options. Future chapters go into more depth on each topic covered in this chapter.

Most of the examples and instructions in this chapter are based on the Unix/Linux command-line CVS client, though I also provide examples using multiplatform clients. Most graphical clients use the CVS command names for their menu options and buttons, so if you're using a graphical client other than one of the ones I provide examples for, you should be able to follow this chapter reasonably easily. Those using Mac OS X can use CVS from the command line, and people using Windows who want to use the command line can use Cygwin (available from http://www.cygwin.com). CVS is available via the Cygwin installer. Graphical clients and clients for operating systems other than Unix/Linux are described in Appendix A.

You may not need to read all of this chapter:

If CVS is installed, and you're working on an existing project that is already stored in CVS, skip the early sections and start at "Checking Out Files." You may need your system administrator (or the person who installed your repository and existing project) to tell you the repository path and project name.
If CVS is already installed and running, with a repository available for your project, go straight to "Importing Projects." You may need your system administrator to tell you the repository path.
If CVS is installed but there is no repository, go to "Building Your First Repository."
For information on installing graphic clients, see Appendix A.

If you're not sure whether CVS is already installed and running, read the first part of "Installing CVS," which tells you how to check. If you're uncertain about having a repository, try searching for the directory

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS is client/server software that runs on Unix and Linux platforms, including Mac OS X. The CVSNT program is a CVS-like server that runs on Windows, and there are CVS clients for Windows, Mac (including pre-OS X Macintosh), Linux, and Unix. When you install CVS on a Unix/Linux server, you automatically get both server and client software. To access CVS across the network from any Unix/Linux machine, install CVS on the machine in question. The server and (command-line) client software are one and the same.

CVS is available from http://cvs.nongnu.org. It is also available as an installation package with many GNU/Linux distributions, including Debian, Red Hat, and SUSE.

A Windows-compatible CVS server is available at http://www.cvsnt.org. This server is not identical to the Unix server, but the differences are clearly listed in the CVS NT FAQ, and an installation guide is available on its web site.

If you are running Mac OS X, Cygwin, Unix, or Linux, you may already have CVS installed. If it's installed and in your path, typing cvs at the command line produces the results shown in Example 2-1.

Example 2-1. CVS help display


$ cvs

Usage: cvs [cvs-options] command [command-options-and-arguments]

 where cvs-options are -q, -n, etc.

  (specify --help-options for a list of options)

 where command is add, admin, etc.

  (specify --help-commands for a list of commands

   or --help-synonyms for a list of command synonyms)

 where command-options-and-arguments depend on the specific command

  (specify -H followed by a command name for command-specific help)

 Specify --help to receive this message



The Concurrent Versions System (CVS) is a tool for version control.

For CVS updates and additional information, see

  the CVS home page at http://www.cvshome.org/ or

  Pascal Molli's CVS site at http://www.loria.fr/~molli/cvs-index.html

If you already have CVS installed, you can skip this section and jump ahead to "Building Your First Repository."

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS relies on a file-based database called the CVS repository. The repository contains all the historic data about your project, including each change that has been committed to the repository, as well as the user making each change. Your developers work from a sandbox which contains working copies of the files in your project. Changes from your sandbox (and other developer's sandboxes) are committed to the repository, and changes in the repository but not in your sandbox are updated from the repository. Figure 2-3 shows a diagram of the relationship between a repository and sandboxes.

Figure 2-3: Repository/sandbox relationship

The repository must be hosted on a machine with sufficient disk space to store your files and all the change data for your projects. The repository should be accessible to all the users from their workstations. Chapter 6 contains more information on choosing a repository server and setting up a more complex repository.

If the repository is on a remote computer, I recommend that users access the repository via SSH. Ensure that the server is running an SSH server and the workstations have a compatible SSH client. For more information on remote repositories and SSH, see "Accessing Remote Repositories" later in this chapter. Chapter 8 contains a full discussion of remote repositories.

For any one project, ensure there is enough disk space for three times the expected final size of that project. If you intend to store binary files, multiply by at least five. After your first project, you'll have a feel for how much space to allow.

A repository can store many projects. If you are creating a repository that might handle several projects of unknown size, estimate as best you can and ensure that you can add more room later.

Not only can one repository store many projects, but one server can store many repositories. It's usual for a server to have only a single repository, though.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

When you have created a new repository, you may want to import your first project—a related collection of files stored under a single directory. It is possible to store a single file under CVS, but it will also be considered a project and you will need to store it under its own project directory. CVS groups things into projects because it needs to be able to create a subdirectory to store metadata about the project.

Your repository can hold one project, or it can hold many different projects. CVS scales well: a repository can help a single person with a small job to do, or can be used by a large company to provide version control to hundreds of separate groups.

Before loading a project into CVS, consider the project's structure. If you move a file after it has been created and stored in CVS, CVS treats it as two files: the original in the original location and the new file in the new location. The history of the file is then split into two parts. Decide how you want to structure the source files for a project before you import it into CVS.

If you will eventually want to distribute your project's files across several unrelated directories, it is best to develop the project under a single root directory, then distribute the files as part of the installation script. Chapter 7 describes the issue of project structure in more detail.

If you have binary files or other files that are not plain text, please see the information on binary files in Chapter 3 before adding them to the repository.

If you have any files or directories named CVS, please rename them before you import them—CVS restricts that name for its own purposes.

Create your initial project directory structure, possibly in /tmp. Once the project is stored in CVS, the repository backed up, and the backup verified, this initial version can be removed (which is one reason to use /tmp). You won't be using it as a sandbox, and the project is duplicated in CVS, so there's no reason to retain it once you have copies in the repository and its backup.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

There are several ways to access a remote repository. This quickstart guide uses the ext method with the SSH protocol, but if your system administrator gives you different instructions, follow those. Chapter 8 explains the use of remote repositories in detail. The ext and SSH approach uses the ext repository access method, with an SSH client as the program that performs the connection. These are also explained in Chapter 8.

Your first step—at least, the first step that I recommend—is to install SSH on the client machine. Make sure that the client-end SSH protocol matches the server's SSH protocol. Set up SSH keys or passwords and test the connection. Using SSH enables you to create a secure connection to the remote repository.

Next, if you're on a Mac OS X, Unix, or Linux system, set the CVS_RSH environment variable on your client machine to the name of your SSH program; usually, this is ssh or ssh2. Graphical clients that support the ext and SSH approach may have ssh as an authentication type option in the dialog that requests the repository path. Check the documentation for your client.

In WinCVS and gCVS, call up the Preferences dialog under the Admin menu and select "ssh" as the Authentication method under the General tab. Under the Ports tab, you may need to enter the name of your SSH program in the option "Check for an alternate rsh name."

In MacCVSX (for OS X), ssh is one of the authentication method options listed in the Preferences dialog. MacCVS for OS 9 and earlier versions do not support SSH as a standard option. Instead, you can make use of SSH from MacCVS via port tunnelling, as described in Appendix A.

If the repository is on the same machine as the client, the repository path is simply the full path to the repository's root directory. On a remote machine, the repository path takes the form:


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

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS stores projects and files in a central repository, but you work from a working copy, the sandbox, in your local directories. You create the sandbox with cvs checkout.

CVS creates the sandbox as a subdirectory of your current working directory. I like to create a directory to contain all my CVS sandboxes, and I use ~/cvs. Run this command from whichever directory you want a sandbox created in:


cvs -d repository_path checkout project_name

It checks out all files for the named project. If your repository is on the local machine, the repository path is the full pathname of the CVS repository. If your repository is on a remote server, see the preceding section, "Accessing Remote Repositories." Example 2-10 shows a local checkout.

Example 2-10. Local repository checkout


$ mkdir ~/cvs

$ cd ~/cvs

$ cvs -d /var/lib/cvsroot checkout example

cvs checkout: Updating example

U example/file1

U example/file2

The checkout command puts a copy of the project's files and subdirectories into a directory named for the project, created in the current working directory. It also puts some administrative files of its own in a subdirectory of the project directory, called CVS.

You can check out an individual file or subdirectory of a project by replacing project_name with the pathname to the file or directory, from the project's root directory. See Chapter 3 for more information.

CVS stores the repository path as part of the sandbox, so you should never again need to use -d repository_path in commands executed within that sandbox.

Note that the repository paths for local or remote checkout are the same as the repository paths for local and remote import. So if you used -d /var/lib/cvsroot for the import, you'd use the same for checkout.

If you are checking out a sandbox from a remote repository, the repository path must follow the remote repository format introduced in "Accessing Remote Repositories," earlier in this chapter. Example 2-11 shows a checkout from a remote repository. Figure 2-6 shows the same checkout with gCVS.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Once you've checked out your project files into a sandbox, you can edit them with your favorite editor. Your sandbox is an ordinary set of files and directories, with an extra CVS subdirectory in each directory. Ignore the contents of the CVS subdirectory, and edit your project files as you normally would.

Some of CVS's functions will not work properly in files with complex formats, such as image or sound files, and these files should be stored in binary format (see Chapter 3 for more information). The default save file format of editors such as Microsoft Word and OpenOffice.org doesn't react well with the line-based diff system that CVS uses, and these files should also be stored in the repository as binary files, using the -kb option to cvs add (as explained in Chapter 3). However, if you save in plain-text, RTF, XML, or HTML format, you can commit them as normal CVS files.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Changes to your sandbox files are not synchronized with the repository until you run the cvs commit command. This command is best run from the root directory of your sandbox, and it must be run from within the sandbox.

Commit to the repository frequently. Rules of thumb for when to commit include "every time the code compiles cleanly" and "every day before lunch and before you leave." Speak to your project manager about the preferred working style, or read Chapter 7 for ideas.

In programming projects with several developers, try to avoid committing code that doesn't compile, unless your project manager tells you that your project is using a different working style.

When you commit, CVS examines each directory and subdirectory under the current working directory. It searches for files that it is tracking that have changed, and commits all changes to the repository. See Example 2-12 for an example of committing files. Remember that the repository path is stored in the sandbox, so you don't need to specify the path explicitly in your cvs commit command.

Example 2-12. Committing files


$ cd ~/cvs/example

$ cvs commit

cvs commit: Examining .

If your repository is not on the local machine and your repository server doesn't have your SSH public key, CVS asks for a password for the remote machine. If the server has the public key, your SSH client can use the private key to authenticate you. It's much easier to use CVS if the server has the public key.

Keeping a public key on the server is a security decision: it's much more convenient to use CVS if you don't have to keep typing in your password, but it also means that if an intruder has access to your shell, he can gain access to the data stored in the repository. I keep my desktop's public key on the server, but not my laptop's. It's always possible that I'll lose my laptop, so I don't want it to have password-free access into our network. The desktop computer is a little bit harder to lose.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The cvs update command checks your sandbox against the repository and downloads any changed files to the sandbox. It complements the cvs commit command, which uploads changes from the sandbox to the repository. Use the -d command option to download new directories as well. Example 2-16 shows the use of cvs update.

Example 2-16. Updating the sandbox


$ cvs update -d

cvs update: Updating .

U file2

cvs update: Updating directory

$ ls

CVS  directory  file1     file2

As with committing, you should not have to specify the repository; it should be stored in the special CVS subdirectory in the sandbox. You must run cvs update from within the sandbox, and it is best to run it from the root directory of the sandbox to ensure that it checks all the subdirectories.

Note that -d means two different things, depending on where it is in the command. Recall that CVS commands take the following form:


 cvs [cvs-options] command [command-options]

As a CVS option, -d defines the repository path. As a command option to the update command, -d downloads directories that were not previously in the sandbox. This is explained in more detail in Chapter 3.

As the update command runs, it generates a list of files that are modified. To the immediate left of each filename is a single uppercase letter. Those letters report the status of each file listed, and they have the following meanings:

A filename: Marked for addition but not yet added to the repository (need to run a cvs commit).
C filename: There was a conflict between the repository copy and your copy. The conflict requires human intervention.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

To add a file to a project in the repository, first create the file in your sandbox. Be sure to consider your project's structure and place the file in the correct directory. Then, issue the following command from the sandbox directory containing the file:


cvs add filename

This command marks the new file for inclusion in the repository. Directories are added with the same command. Files within a directory can't be added until the directory itself is added. A file is only marked for addition when you run cvs add; it is actually added to the repository when the next cvs commit is run. A directory is added to the repository immediately. Example 2-19 shows a file being created and added to the repository. Remember that the file is not actually stored in the repository until the cvs commit command is run. Figure 2-10 shows the same file addition in gCVS.

Example 2-19. Adding files


$ touch file3

$ cvs add file3

cvs add: scheduling file 'file3' for addition

cvs add: use 'cvs commit' to add this file permanently

$ cvs commit

...

Log message editor opens

...

RCS file: /var/lib/cvsroot/example/file3,v

done

Checking in file3;

/var/lib/cvsroot/example/file3,v  <--  file3

initial revision: 1.1

done

Figure 2-10: Adding files with gCVS

If you have binary files or other files that are not plain text, please see the section "Binary Files and Wrappers" in Chapter 3 before adding them to the repository. These files should be added with the -kb command option.

As with committing for other reasons, an editor window will open asking you to enter a log message describing the files to be added.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

To remove a file from the repository, first remove the file from the sandbox directory, then run the following command from the sandbox directory that contained the file:


cvs remove filename

The deletion does not take effect until the next cvs commit command is run; the file remains in the repository until then.

Example 2-20 shows a deletion, and Figure 2-11 shows the same deletion in gCVS. After the cvs commit is run, CVS doesn't remove the file entirely; it puts it in a special subdirectory in the repository called Attic. This step saves the file history and enables the file to be returned to the repository later.

Example 2-20. Removing a file


$ rm file3

$ cvs remove file3

cvs remove: scheduling 'file3' for removal

cvs remove: use 'cvs commit' to remove this file permanently

$ cvs commit

...

Log message editor opens

...

Removing file3;" 9L, 308C written

/var/lib/cvsroot/example/file3,v  <--  file3

new revision: delete; previous revision: 1.1

done

Figure 2-11: Removing a file with gCVS

CVS opens an editor so you can record the reason for the file deletion, as it does when you commit changes.

CVS does not remove directories from the repository, because doing so would break the change tracking. Use the -P flag to cvs checkout and cvs update to avoid empty directories in your sandbox.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

When you're ready to compile and test a program, to send a book to an editor, or to post a web site to the server, you will want a copy of the project that doesn't have the CVS administrative files. You could use cvs checkout and remove the CVS subdirectories, but that's tedious and unnecessary. Use cvs export instead. It works exactly the same as checkout, but doesn't create the administrative files necessary for a sandbox.

If you need to compile a program, distribute the project's files, or otherwise modify the results of the export, I recommend using a build tool such as make on the exported project. Unfortunately, the use of make is beyond the scope of this book, but I recommend the article "Introduction to Make" at http://www.linuxdevcenter.com/pub/a/linux/2002/01/31/make_intro.html.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS is a tool for improving project development and system maintenance. Like all tools, there are ways to use it most efficiently:

Synchronize the clocks of computers sharing a repository to the same universal time. CVS relies on file timestamps to determine which files have changed. NTP (Network Time Protocol) is a very useful tool for time synchronization.
Give each developer his own sandbox, and communicate all file changes through CVS. This method maintains change tracking and prevents developers from irretrievably overwriting each other's work.
Update frequently, at least before starting work every day, to keep your sandbox current.
Commit frequently to keep your repository current. Programmers typically commit every time their code compiles cleanly; other people may commit after completing each block of work.
Programming teams: use build-management tools and ensure that all files in the build are committed to the repository. Ensure that builds for testing or release come from the repository rather than a sandbox, but allow sandbox builds for programmers to do prealpha tests.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

This chapter provides a thorough discussion of the most critical CVS commands and topics. It is designed for end users who do not have to administrate the repository and who do not have to make changes that affect the entire project.

The commands explained in this chapter include checkout, commit, update, release, add, remove, ls, and status. Other topics explained in this chapter include sandboxes, merging, conflicts, binary and special files, keywords, editing files in CVS, and the CVS command syntax.

This chapter assumes that you have installed CVS, set up a repository, and created a project. Instructions for these tasks are in Chapter 2. Chapter 2 also touches on many of the commands in this chapter, but this chapter provides a full explanation of their uses.

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.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

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.

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.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

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

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.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Files are edited in the sandbox, but changes to the sandbox have no effect on the repository until they are committed. The cvs commit command uploads changes from the sandbox to the repository. After determining which files need to be changed in the repository, cvs commit opens an editor and expects you to enter a log message.

"Choosing Your Editor," earlier in this chapter, explained how to change the default editor.

The syntax of cvs commit is:


 cvs [cvs-options] commit [command-options] [filename]

cvs commit has only a few options, the most useful of which are:

-f: Force a commit even if there are no changes to the file. (This option implies -l as well.)
-l: Perform a local, nonrecursive commit operation on the current working directory only.
-R: Perform a recursive commit operation on all subdirectories, as well as the current directory (default).
-m message: Provide a log message.
-F filename: Provide a log message from the specified file.
-r revision: Set an updated revision number (not recommended for novice users).

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The cvs commit command uploads changes from the sandbox to the repository; cvs update downloads changes from the repository to the sandbox. The two commands complement each other, and you need to call both to keep the sandbox synchronized with the repository. Use cvs commit when you have changed sandbox files since your last commit; use cvs update when you know that the repository has been changed since you last updated, or when you wish to check whether it has changed.

cvs update attempts to preserve any changes you have made to your sandbox since you last synchronized it with the repository. These changes will be merged into the files retrieved from the repository. If you intend to overwrite your sandbox files with a clean repository copy, use the -C (clean) option in conjunction with any other options. Most often, you will use -C when you want to discard changes, but you can also use the -r (retrieve by revision), -D (retrieve by date), or -A (clear sticky tags) options.

Example 3-6 shows output from cvs update executed with the -d option. The -d option instructs CVS to download new directories from the repository to the sandbox. Figure 3-6 shows Cervisia immediately after an update.

Example 3-6. Using cvs update


bash-2.05a$ cvs update -d

cvs server: Updating .

cvs server: Updating doc

cvs server: Updating doc/design

U doc/design/Analysis.rtf

U doc/design/Specification.rtf

cvs server: Updating doc/plan

U doc/plan/Schedule.rtf

cvs server: Updating lib

cvs server: Updating man

cvs server: Updating src

M src/wizzard.h

Figure 3-6: Update with Cervisia

cvs update displays symbols next to each file it downloads. The symbols report file status, similar to those reported by cvs status. You'll see the following symbols in

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Use cvs add to add a file or directory to the repository. Using cvs add on a file marks the file as needing to be added when cvs commit is run. Running cvs add on a directory adds the directory to the repository and the CVS subdirectory to the directory.

The Attic and CVS directories are special directories that CVS uses for its own purposes. Do not make a file or directory with these names.

If you attempt to commit and get an error message that includes *PANIC* administration files missing, you may have created a file or directory named CVS. This message means that CVS could not find the Repository file in the CVS subdirectory of the sandbox directory that it is trying to commit.

You can use cvs remove to remove a file that has been added but not committed. This command removes the marking in the CVS subdirectory and doesn't record the aborted addition in the repository's history. Similarly, you can use cvs add to abort a file removal; it resurrects the file without recording the aborted removal.

The file or directory to be added must exist within the sandbox, and a directory must not contain a file or subdirectory named CVS.

Files and directories are case-sensitive in the repository. If you are using a CVS client or operating system that is not case-sensitive, you may encounter problems. Avoid using file or directory names that would be the same if case were not an issue.

In the process of adding a file, CVS strips trailing slashes and any special CVS files from the arguments, then checks for name conflicts (including some case-comparison testing). If CVS detects a name conflict, it notifies the user and does not add the file or directory.

cvs add has the following syntax:


cvs [cvs-options] add [command-options] filename

The available options are

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The cvs remove command is used to mark a file as removed in the repository. The file isn't actually removed from the repository; it is stored in a special directory called Attic, so that its earlier revisions can be recalled. The file is no longer sent to sandboxes, and it is removed from existing sandboxes at the next cvs update, which displays the message cvs server: filename is no longer in the repository.

A removal must be committed before it affects the repository. If you notice that you accidentally removed a file you need (before you run cvs commit), you can use cvs add to undo the removal and then use cvs update to retrieve the removed file. This process leaves no record in the repository. Similarly, if a file has been added but not committed, cvs remove undoes the addition and leaves no record in the repository.

If someone else modifies a removed file before the removal is committed, the commit will fail and report a conflict. Resolve the conflict by unremoving the file with cvs add, checking the changes with cvs update or cvs diff, and removing the file again if desired. I strongly recommend speaking with the person who modified the file before you resolve such a conflict, lest you remove a file that should be retained.

To use cvs remove on a file, the file must not exist in the sandbox or you must call the cvs remove command with -f. Usually, I delete the file from the sandbox before running cvs remove.

The syntax for cvs remove is:


cvs [cvs-options] remove [command-options] filename

cvs remove has the following options:

-f: Delete the file from the sandbox.
-l: Perform a local, nonrecursive operation on this directory only.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

There is no CVS command designed specifically to move a file or file directory. In fact, CVS's design doesn't accommodate such moves. However, you can work around this limitation using a combination of CVS commands, or by altering the repository using operating-system commands. Moving files can make project history difficult to track, because then a file's history is recorded across two different files in different locations. Minimize this potential source of confusion by recording the new and old locations with meaningful log messages.

To rename a file or directory at the operating-system level, "move" it from the old filename to the new filename. For example, use the mv command on Unix, Linux, and Mac OS X; on Windows, you can use the move command.

The recommended way to move a file is to use cvs remove followed by cvs add, with messages that state where the file was moved from and to. This method preserves the file's history and allows reversion to earlier versions of the project in its old location. However, the messages stored with the add and remove commands are the only record of the move. Example 3-19 shows this method being used to rename the wizzard.h file.

Example 3-19. Renaming a file


bash-2.05a$ mv wizzard.h config.h

bash-2.05a$ cvs remove wizzard.h

cvs server: scheduling 'wizzard.h' for removal

cvs server: use 'cvs commit' to remove this file permanently

bash-2.05a$ cvs add config.h

cvs server: scheduling file 'config.h' for addition

cvs server: use 'cvs commit' to add this file permanently

bash-2.05a$ cvs commit

.

.

.

Moving src/wizzard.h to src/config.h

CVS: ---------------------------------------------------------------------

CVS: Enter Log.  Lines beginning with 'CVS:' are removed automatically

CVS:

CVS: Committing in .

CVS:

CVS: Added Files:

CVS:  config.h

CVS: Removed Files:

CVS:  wizzard.h

CVS: ---------------------------------------------------------------------

.

.

.

RCS file: /var/lib/cvs/wizzard/src/config.h,v

done

Checking in config.h;

/var/lib/cvs/wizzard/src/config.h,v  <--  config.h

initial revision: 1.1

done

Removing wizzard.h;

/var/lib/cvs/wizzard/src/wizzard.h,v  <--  wizzard.h

new revision: delete; previous revision: 1.5

done

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The cvs release command should be used before you delete a sandbox. CVS first checks whether there are any files with uncommitted changes; then, if all is well, CVS runs cvs unedit on each file to signal that you no longer intend to edit the files, and writes to the history file in the repository to state that the sandbox was released. (The CVS unedit command is explained in Chapter 5; the history file is explained in Chapter 7.) CVS also reports on files and directories that are not currently stored in the repository.

If there are uncommitted changes, CVS alerts you to the changes and does not release the sandbox. You can either use cvs commit to commit the changes, remove the changed files manually, or use cvs update -A to revert to a state where you can release the sandbox (and lose the changed data).

It's not strictly necessary to use cvs release before deleting a sandbox. You can delete a sandbox with no effect on the repository. However, if you get into the habit of using cvs release, you'll remember to use it the one time you do need to run an unedit or when you have made an uncommitted but important change.

The syntax for cvs release is:


cvs [cvs-options] release [-d] directory

The only option for cvs release is -d, which deletes the sandbox after checking it for uncommitted changes. You can use cvs release on an entire sandbox or on a subdirectory within the sandbox.

When you execute cvs release, you must specify a directory, but you can use a dot (.) to indicate your current working directory. Example 3-20 shows use of cvs release to release the wizzard sandbox. Note that a dot is used to specify the current working directory as the sandbox to release.

Example 3-20. Using cvs release


bash-2.05a$ cvs release .

cvs server: warning: src/wizzard.h is not (any longer) pertinent

? src/test

? src/test.c

U src/config.h

U src/main.c

You have [0] altered files in this repository.

Are you sure you want to release directory '.':

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS recognizes keywords that you can embed in any source file other than a binary file. When CVS finds a keyword in a file that it is checking out, it expands the keyword to provide metadata about the latest revision of the file. CVS keywords take the following form:


$Keyword$

Example 3-21 shows a file that includes CVS keywords.

Example 3-21. CVS keywords


# Makefile for the Wizzard project

# First created by J Vesperman, 1 September 2002

#

# Current revision $Revision$

# On branch $Name$

# Latest change by $Author$



# Initial declarations

CC=gcc

SUBDIRS = man doc src lib



# Declaring phony targets

.PHONY: all clean install



all: wizzard

      echo "all: make complete"



clean:

      rm -f src/*.o

      rm -f wizzard

      echo "clean: make complete"

.

.

.



# Log record for Makefile changes:

# $Log$

Example 3-21 shows a makefile. The keywords are expanded when the file is checked out or updated. Example 3-22 shows the resulting expansions.

Example 3-22. Expanded keywords


# Current revision $Revision$

# On branch $Name$

# Latest change by $Author$ on $Date$



# Initial declarations

CC=gcc

SUBDIRS = man doc src lib



.

.

.



# Log record for Makefile changes:

# $Log$

# Revision 1.6  2004/04/16 16:15:52  chodacki

# sfcleanup fixes

#

# Revision 1.5  2003/07/11 20:00:23  madd

# madd final SC edits

#

# Revision 1.4  2003/07/09 21:31:56  madd

# madd SC edits

#

# Revision 1.3  2003/07/07 21:52:50  madd

# madd SC edits

#

# Revision 1.2  2003/06/27 21:47:43  madd

# madd R2 conversion edits

#

# Revision 1.1  2003/06/26 22:22:10  madd

# Initial revision

The full list of possible keywords is provided in Chapter 11. These are the most commonly used keywords:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The default CVS method of handling file conflicts works well for text files, because CVS can determine which lines have changed and add or remove them as appropriate. It doesn't work well on binary files, because such files are not usually built around lines of text separated by carriage returns.

Some files with textual content are not actually text files, as they contain binary formatting codes or nonstandard line endings. Files such as those created by Microsoft Word or OpenOffice.org should be flagged as binary, because line-by-line merging and keyword expansion could damage the saved data.

CVS doesn't work for device files, symbolic links, or other files that cannot be modified and moved. Rather than trying to store these files in CVS, include the commands to create or connect them in your build scripts.

For binary files, CVS uses a different method of conflict resolution. The two methods CVS has available are MERGE and COPY. MERGE is the default CVS method. COPY instructs CVS to provide the user with both versions of the file if there is a conflict, so the user can blend the changes manually and recommit.

Binary files should be added to CVS using the -kb command option to cvs add. If the expansion mode is not set at the time the file is added, the -kb command option to cvs admin sets the mode retroactively. This option informs CVS not to expand keywords, not to modify line endings, and to use the COPY method of conflict resolution. Example 3-23 shows the use of these command options. Note the use of cvs admin to change the way the AcceptanceTest.doc file is stored. This user was lucky enough to have a pristine copy of that file around, because checking it in as a regular, nonbinary file almost certainly rendered the repository version unreadable.

Example 3-23. Setting keyword expansion for binary files

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

If you find yourself regularly using the same options with a command, you can use the .cvsrc file to set default options and minimize your typing. If the .cvsrc file is in your home directory on your client machine, CVS reads the file, looks for the CVS command you are currently running, and runs the command with the options specified for that command in the file. To temporarily avoid parsing the .cvsrc file, use the -f CVS option.

The .cvsrc file format is one line per command. Start a line with the command that you want to modify followed by the options you want as the default. You can also specify default CVS options in the .cvsrc file. To do so, use cvs as the command.

Example 3-25 shows a .cvsrc file. This file specifies a default description for adding files, specifies (using -P) that update and checkout prune empty directories, and specifies (using -q) that CVS run quietly, but not as quietly as it would with the -Q option.

Example 3-25. A .cvsrc file


add -m "Part of the wizzard project"

update -P

checkout -P

cvs -q

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

One of the most helpful—yet underused—facilities of CVS is the tag. CVS's tagging feature allows you to label a revision for later retrieval. This feature also allows you to fork development so that you can work on two or more lines of development of your project simultaneously. The line that has been forked off is called a branch, and the original line is called the trunk.

If your project has never been branched, the project is on the trunk.

This chapter explains tags, branches, and how to merge branches and trunks. It also discusses why and when to branch and provides strategies and hints for using branches effectively in your project.

CVS allows you to retrieve any checked-in revision of a file. Although retrieving revisions of individual files is useful, it's even more useful to be able to retrieve the compatible set of revisions that make up a complete, functional version of a project, such as all the revisions that become release 1.0 of a program, or that become the first edition of a book. This ability is also important for compliance with standards and regulations.

Tagging is a way of marking a group of file revisions as belonging together. You can't use the revision numbers for this purpose, because revision 2.3 of one file might belong with revision 2.17 of another. Figure 4-1 shows a group of file revision numbers, with an imaginary string denoting which revision numbers belong to the same release.

Figure 4-1: File revisions that belong together

CVS allows you to create a single tag that denotes all the file revisions that connect to that virtual string. When you want to look at all the file revisions that belong to a tag, CVS can "pull the string" to locate the tagged revisions. Figure 4-2 shows the same group of files, with the string pulled tight to show which set of revisions belong to that tag.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS allows you to retrieve any checked-in revision of a file. Although retrieving revisions of individual files is useful, it's even more useful to be able to retrieve the compatible set of revisions that make up a complete, functional version of a project, such as all the revisions that become release 1.0 of a program, or that become the first edition of a book. This ability is also important for compliance with standards and regulations.

Tagging is a way of marking a group of file revisions as belonging together. You can't use the revision numbers for this purpose, because revision 2.3 of one file might belong with revision 2.17 of another. Figure 4-1 shows a group of file revision numbers, with an imaginary string denoting which revision numbers belong to the same release.

Figure 4-1: File revisions that belong together

CVS allows you to create a single tag that denotes all the file revisions that connect to that virtual string. When you want to look at all the file revisions that belong to a tag, CVS can "pull the string" to locate the tagged revisions. Figure 4-2 shows the same group of files, with the string pulled tight to show which set of revisions belong to that tag.

Figure 4-2: Tagged file revisions

A tag can mark a specific revision of a single file or a specific set of revisions of a group of files—in essence, naming the string. The tag then gives you a convenient way to retrieve that revision or matched set of revisions. Remembering the significance of a text string is much easier than remembering a version number, not to mention a handful of different version numbers for each file. Tags are often used to record the version number used by the developers, rather than the CVS revision number, which is used primarily as a CVS internal designation.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Stickiness is an important concept in CVS, especially when talking about tagging and branching. Stickiness is primarily internal to CVS, but it affects what can be done in a sandbox.

When a file in a sandbox has a persistent state that is not the default state in the repository, the persistent state is said to be sticky. A sandbox copy of a file can be set to a specific revision, belong to a branch, or have specific keyword options. Any of these things can cause a file to be sticky.

A file can be set to a specific revision by being retrieved from the repository with a tag, revision number, or date. If the file is retrieved with a date, it is said to have a sticky date. If it is retrieved with a tag, it is said to have a sticky tag, and if it is retrieved with a revision number, it is said to have a sticky revision.

Along the same lines, a sandbox file that belongs to a branch is said to have a sticky branch, and a sandbox file with sandbox-specific keywords has sticky keywords.

A sticky state applies to all commands run on the file. A file with a sticky date, revision, or nonbranch tag will not be updated to a more recent copy; nor can such files be committed. A file with a sticky branch is always committed to or updated from the branch in question.

Sticky states on a file can be viewed with cvs status. For example, use the command cvs status index.htm to see the status for the index.htm file. Example 4-8 shows a cvs status report that lists a sticky branch.

Example 4-8. Viewing a sticky file


bash-2.05a$ cvs status main.c

=============================

File: main.c                Status: Up-to-date



   Working revision:     1.9

   Repository revision:  1.9     /var/lib/cvs/wizzard/src/main.c,v

   Sticky Tag:           beta_0-1_branch (branch: 1.9.2)

   Sticky Date:          (none)

   Sticky Options:       (none)

Sandbox directories can also have sticky states, and a directory with a sticky state applies that state as the default to any file added to that directory. Sticky states in a directory can be seen in the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

In the introduction to this chapter, I defined a branch as a forked line of development in your project, with the line that has been forked off called the branch, and the main line the trunk. CVS builds the branch and the trunk from the same source data, up until the point at which they diverge, which is called the base of the branch. From that point, CVS stores the changes made to the branch separately from the changes in the trunk. Revisions on the branch are given their own revision numbers, based on the revision number of the base of the branch.

You can branch a single file, any group of files, or a whole project, just as you can tag individual files or any group of them. I usually recommend branching a project. In my experience, if you branch one file, you will eventually need to branch others in the project for the same reason. It is much easier to keep track of a single branch over the whole project than a group of unrelated branches of individual files.

A tag marks a specific revision of each tagged file, and a sandbox checked out with that tag cannot be changed (you can edit the files, but when you try to check them in, you'll get the error sticky tag 'tag' for file 'file' is not a branch). In contrast, a branch creates revisions that can be edited, committed, checked out, updated, and tagged independently of the revisions on the trunk. In many ways, a branch can be treated as an independent development line of a project.

You can tag a file with any number of tags, as long as each tag name in that file is unique, including any tags on the branch. CVS relies on each tag and branch name to be unique within each file, so it considers the branch name to be a tag name when determining tag uniqueness.

A branch is an ongoing line of development, and any tags on the branch are used to mark the specific revisions when significant events occur. Though branches are created with the cvs tag command, branches and tags are different things. A branch represents multiple revisions and a tag represents a single revision.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

This section explains the basis of branching strategies and the two main philosophies of branching. It also provides some answers to the question of when and why you should branch on a project.

The general rule of thumb for branching is that you should keep the main line of development on the trunk; everything else can be branched. The problem is determining the main line of development. Should the trunk contain stable code or unstable code? Should each release be branched when it goes to be tested? Should new features be developed on the trunk or on a branch?

These decisions all stem from two distinct definitions of "the main line of development." These two definitions result in two different branching philosophies, distinguished here as basically stable and basically unstable.

Section 4.4.1.1: Basically stable

The basically stable branching philosophy states that the trunk should contain project data that is always close to being ready for release. Branches are used for development, bug fixes, prerelease quality assurance (QA), and refactoring. Branches are also used for experimental code.

The strictest variation of this philosophy states that nothing should be merged to the trunk until it has been through QA. This ensures that at any time a release candidate can be taken from the trunk, put through a small amount of QA, and then published or sold.

More lenient variations of this philosophy allow anything that passes developer unit-testing to be merged into the trunk. Such a relaxed approach requires a release candidate to be branched off and put through a full QA analysis before publication.

Advantages of the basically stable method include the following:

You can take a snapshot of the trunk at any time, run it through QA, and publish it.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Chapter 3 contains a section on merging and resolving conflicts ("Updating the Sandbox Files from the Repository"). Conflicts are rare when the developers are working solely on the trunk and frequently committing to the same line of development. However, once a development team starts using branches, there is the potential for lines of development to be kept separate from each other for months at a time. This vastly increases the possibility for conflict, so I am expanding on the process of merging and resolving conflicts. Please read the section in Chapter 3 first, however, as this discussion is based upon knowledge of the information provided there.

The process for a merge is as follows:

If you're trying to merge a branch to a trunk, a branch to another branch, a trunk to a branch, or any other such combination, go to step 2. In all other cases, try to commit. If the commit succeeds, the process is finished. Otherwise, continue.
Run update to blend the files. Watch to see whether any files have conflicts. If none do, the process is finished. Otherwise, continue.
For each file that has a conflict, edit the file (text mode) or use the merge tool in your graphic client. Note the conflicting lines.
If the conflicting lines can peacefully coexist in the file, edit out the conflict markers and any duplicate lines. Go on to step 7.
If you need to consult with a coworker to decide what to do about the conflicting lines, use log or annotate to determine who wrote them. Consult with your coworkers and decide how to correct the conflict.
Edit the files to correct the conflict, remove conflict markers and remove any duplicate lines.
Check for any additional conflict markers in the current file. If there are no additional markers, commit the file. Otherwise, go back to step 3.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

This chapter explains how CVS can be used for source or content control—how to manage a group of developers working together on a project without having them overwrite each other's work, causing loss of data. It also describes commands that show what each person has done to a file.

The problem of source control occurs when you don't have any management software. If you have a central location for data and two people are using the same storage, such as the same file, the second person to save that file will overwrite the first person's changes. Source control software can prevent this, either by capturing both sets of changes and merging them together, or by preventing two people from having the same file checked out at the same time.

CVS is designed to allow developers to work simultaneously on a file. Several people can work on the same file, each in their own sandbox, and CVS tries to merge their changes to the data in the central repository. If the changes can't be merged easily, the developer who commits the second set of changes is asked to resolve the conflict. This pattern is explained in Chapter 3.

An alternative to simultaneous development is exclusive development, where one developer at a time has the editing rights for a file. Some development teams prefer to use exclusive development, which is effective for files that can't be merged. CVS supports the exclusive development of files with a choice of two methods:

The first method permits, but does not enforce, exclusive development. This method uses the cvs watch, cvs edit, and cvs unedit command set.
The second method uses the cvs admin command to emulate file locking with reserved checkouts and relies on the rcslock script in the contrib directory of the CVS source code. This method requires that the user have privileges to modify the repository, or the assistance of the repository administrator.

Whether you use exclusive or simultaneous development, source control works only if your project members use it. It is also essential that they communicate the basic design and structure of the project with each other. No source control system can take the place of a shared vision of the project.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Simultaneous development allows multiple developers to work on the same file at the same time. If you and your coworker are working on different sections of a file, you can both edit the file and then have a program (such as CVS) merge the two versions of the file. Simultaneous development is also useful when you have developers distributed across many time zones, as it eliminates the need to check with other team members before editing a file.

CVS supports simultaneous development without requiring any configuration changes or setup. Simultaneous development is most helpful when you are using text or other line-based files, because CVS merges are based on the changes in lines. CVS is less adept at merging binary files.

When multiple developers use the same repository directory, each should check out her own sandbox, develop in that sandbox, commit to the repository frequently, and update frequently. CVS merges most changes automatically, and if you update and commit frequently, there should be few cases where a human has to merge conflicting changes.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS provides a set of commands to notify users when a file is being edited or committed. You can use these commands to monitor what each member of your team is doing and reduce the necessity of merging files when cvs update is run. Together, the cvs watch, cvs edit, and cvs unedit commands make up the watch method of exclusive development, which is a lightly enforced method of exclusive development.

The watch method requires the repository administrator to set up the notify and users files in the CVSROOT directory of the CVS repository; it requires the developers to check whether a file is being edited before they attempt to edit it.

Use cvs watch like this:

Check out your sandbox, including the files you want to watch.
Issue the cvs watch on command to mark files for watching. (This does not set you as the watcher for the files; it just informs CVS that the files can be watched.) Once a file has been marked for watching, it remains marked unless it is cleared with cvs watch off.

You need to run cvs watch on for a file only once, unless someone clears the setting. Usually, your project leader decides which files can be watched and marks those files for watching.
Issue the cvs watch add command to set yourself as a watcher of the files you want to watch.
Issue cvs edit to inform CVS and other users that you intend to edit a specific file. Other users watching the file will be notified that you are editing it.
Edit the file in any editor.
Commit your changes with cvs commit. This command saves the changes to the repository and releases the file for others to edit. CVS notifies other users watching the file that you have committed it.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS has a method of exclusive development that is based on reserving the ability to commit files, so that only a single user can commit a reserved file. This feature is useful when you want to enforce exclusive development, especially when you have files that cannot be merged and users who are not comfortable with the honor system that cvs watch relies on.

This method requires the rcslock script (distributed in the contrib subdirectory of the CVS source code), file locking set to strict (the CVS default), the assistance of the repository administrator, and the active support of the developers. The rcslock script is provided as is; currently, it is an unsupported part of the CVS distribution.

File locking is set to strict by default in CVS, so there should be no need to set it that way manually. You can confirm the lock status of a file with the command cvs log -h filename.

Do not use the cvs admin -U command on any files in your project. This sets file locking to nonstrict and can cause problems. File locks can be set strict again with cvs admin -L.

The rcslock script is distributed with the CVS source code. Chapter 2 includes the URL for the CVS source code, and most Linux or Unix packaging systems include an option to install the source from the package. The file in the package may be an rcslock.pl or an rcslock.in file, or even just rcslock. In recent versions of CVS, the CVS build script attempts to generate a version called rcslock, with a Perl invocation as the first line.

You may also find an rcslock that corresponds to your installed version of CVS lurking somewhere on your filesystem. For example, on Mac OS X, you can find it in /usr/share/cvs/contrib/rcslock. On Ubuntu, it's the (compressed) file /usr/share/doc/cvs/contrib/rcslock.gz.

Install the rcslock script by copying it from the contrib directory to a sensible location and ensuring that your CVS users have permission to execute it. I recommend using

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

As your project develops, you sometimes need to compare a current revision with an old one, or compare two older revisions with each other. This usually happens when several developers are working on the same file and you need to know which changes were made to a file since you last worked on it.

The cvs diff command compares two revisions of a file and displays the differences. It uses a version of the GNU diff program internal to CVS; this code is also used when revisions are merged during cvs update.

The diff command and the similar rdiff command are also useful for creating patches to be installed by the GNU patch program.

cvs diff has the following syntax:


cvs [cvs-options] diff  [command_options] [filenames]

You can call cvs diff with filenames, directories, or module names. If you don't give a filename, the current working directory is the default.

Usually, you call cvs diff with at least one -r tag or -D date command option. If you invoke it with a single -r or -D parameter, CVS compares the current copy in the working directory with the version in the repository. For example, if you check out revision 1.6 of Makefile, edit the file, then run cvs diff -r 1.6 Makefile, diff displays the changes you made to Makefile since you checked it out.

If you invoke cvs diff with two -r or -D options, CVS compares the two revisions against each other. The command cvs diff -r 1.5 -r 1.7 Makefile displays the changes between revisions 1.5 and 1.7.

Example 5-14 shows a diff command that compares revisions 1.2 and 1.3 of the Makefile file, using the -c option to display a few lines of context around each change. The output starts with a header listing the filename, the repository copy of the file (listed as RCS file), the revisions to be retrieved, the diff options, and the number of times the revisions were committed.

Example 5-14.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The cvs annotate command displays the most recent change for each line of a file in the repository. This command is very helpful when you need to know which change broke the compilation or who rewrote a key paragraph in the documentation incorrectly. This command works off the repository copy, not the sandbox copy, so it does not show any changes in the sandbox that were not committed.

For each line, cvs annotate shows the revision number for the last change, the user, the date, and the contents of the line. This is a quick way of discovering who made which change. Example 5-17 shows some of the annotations for the wizzard.h file.

Example 5-17. Using cvs annotate


bash-2.05a$ cvs annotate src/wizzard.h

Annotations for src/wizzard.h

***************

1.6     (doppel   15-Apr-06): #include "config.h"   /* using autoconf */

1.6     (doppel   15-Apr-06): #include "options.h"  /* manual options that can't

1.1     (jenn     11-Apr-06):

1.2     (jenn     13-Apr-06): #define TRUE 1

1.2     (jenn     13-Apr-06): #define FALSE 0

cvs annotate has the following syntax:


cvs [cvs-options] annotate [command-options] [filenames]

If you don't provide a filename, cvs annotate attempts to run annotate on all the files in the current sandbox. The filenames can be directories or modules.

annotate doesn't work correctly on binary files. CVS tries to display them as text files, which can trigger the bell character and mess with your terminal window.

Use the -F option to run cvs annotate on binary files. You can select which revision to display with -D date and -r revision (or tag), and you can use the -f option to force CVS to use the most recent revision on the trunk if no revision matches the specified date, revision, or tag. cvs annotate uses the usual -l and -R options to control local and recursive operation, respectively.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The cvs log command displays information about files, directories, or modules. You pass a parameter to specify which file, directory, or module you are interested in. If you don't specify anything, cvs log displays log information about all files in the current sandbox directory. The user-provided part of this log information is entered when you run cvs commit or when you set the -m command option to cvs add.

cvs log is often used to help decide which of two revisions to use to create a patch file, to determine a branch point, or to provide a quick guide to what the other developers are doing in a multiuser environment. Informative log messages are very important for all of these uses.

The options to cvs log reduce the amount of information it shows. By default, it displays everything it can. For each file, it displays a header; then, for each revision of the file, it displays the revision number, date, author, state, log message, and number of lines added and deleted in that revision.

Example 5-18 shows a simple use of cvs log. Note that the keyword-substitution mode is the default mode, generating both keyword and value, and that the log message in revision 1.1 mentions both files that were added at the time.

Example 5-18. Using cvs log


bash-2.05a$ cvs log main.c

RCS file: /var/lib/cvs/wizzard/src/main.c,v

Working file: main.c

head: 1.9

branch:

locks: strict

access list:

symbolic names:

     beta_0-1_branch: 1.9.0.2

     beta_0-1_branch_root: 1.9

     pre_beta_0-1: 1.8

keyword substitution: kv

total revisions: 9;     selected revisions: 9

description:

----------------------------

revision 1.9

date: 2005/09/12 08:14:19;  author: jenn;  state: Exp;  lines: +0 −0

Final test of re-addition methods.

.

.

.

----------------------------

revision 1.1

date: 2005/09/11 13:33:13;  author: jenn;  state: Exp;

Added main.c: parses parameters and calls functions in other files.

Added wizzard.h: defines compile-time global variables.

=============================

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Topics covered in this chapter include repository creation, configuration, security, backup, and recovery. It also covers the structure of the repository and the sandbox, the file locking that CVS uses internally, how to edit the repository manually, and the CVS administrative files and environment variables. This chapter is about the repository and the projects stored in it. If you want a quick guide to creating an initial repository, see the instructions in Chapter 2.

In this chapter, I assume that the reader is skilled with Unix and/or Linux operating systems. Running Linux, by Matthias Kalle Dalheimer and Matt Welsh (O'Reilly), is an excellent introduction to Linux systems. Learning the Unix Operating System, by Jerry Peek et al. (O'Reilly), provides information on Unix.

Repository administrators using CVSNT can still use the information in this chapter: I have tried to identify places where I use Unix/Linux-specific terminology, and to provide a generic term as well. There are differences between the CVSNT and the CVS server, so the instructions given here will vary from those for CVSNT.

CVS on Mac OS X behaves just like it does on Unix and Linux, so Mac users will be able to open a Terminal window and follow the instructions in this chapter.

CVS uses the term CVSROOT in two different ways. As the environment variable, it refers to the root directory (topmost folder) of the repository. However, inside the repository is a directory called CVSROOT. To avoid confusion, this chapter never refers to the root directory of the repository as CVSROOT, and, except when mentioning the environment variable, this chapter uses the term CVSROOT solely to refer to the CVSROOT subdirectory of the repository root directory.

If your repository is in /var/lib/cvs, then /var/lib/cvs is the repository root directory and /var/lib/cvs/CVSROOT is the repository's CVSROOT directory.

The repository root directory and the administrative files should be owned by a user made specifically for CVS; typically, the user is named

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The repository root directory and the administrative files should be owned by a user made specifically for CVS; typically, the user is named cvs. This system reduces the damage a malicious or careless user can do to the repository, as long as she doesn't have root (superuser) access.

To create a repository, create the directory that you want to use as the repository root directory on the computer that will act as the CVS server and ensure that the repository root directory is owned by the user who will ultimately own the repository. A recommended repository root directory is /var/lib/cvsroot.

Execute the command cvs -d repository_root_directory init, where repository_root_directory is the name of your directory: this command sets up that directory as a CVS repository. The root directory given must be an absolute path, not a relative path. Example 2-5 (in Chapter 2) shows repository creation.

The cvs init command sets up the directory as a CVS repository by creating the CVSROOT subdirectory and the initial files for CVSROOT, with their default configurations.

A repository may hold many projects, so to determine how much space you need to allow for your repository, you need to calculate the space for each project. The repository itself will have a small amount of overhead: I allow 500 K for a small repository, and a megabyte or two for most commercial repositories.

For any project, ensure enough room on the partition for three times the expected final size of the project. If you intend to store binary files, multiply their expected size by at least five. Monitor the repository's partition; your users may have a use pattern that requires more or less space than this.

For most projects, the amount of RAM on the repository server is not an issue. CVS is usually modest in its memory requirements, and a server with 256 MB of RAM can handle most repositories. The two major areas of memory use are large

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

A CVS repository that is no longer needed can be removed as you would remove a normal directory tree. All the information CVS stores about the repository and the projects in it are stored within the repository tree, most of it in the CVSROOT subdirectory of that repository.

If you have edited the scripting files in the CVSROOT directory, they may refer to scripts stored elsewhere. Check the scripting files; if the referenced scripts are no longer needed, they can also be removed.

Once you have backed up any projects you may need to refer to later, remove the repository with rm -rf repository_root_directory.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The security of your projects relies on the security of your CVS repository, the repository's computer and its environment, all the computers that contain sandboxes, your access method, your backup storage, and your developers' working environments. The security of access methods is covered in Chapter 8. General computer security is outside the scope of this book, but you should consider it when securing your repository.

Both sandbox and repository security is based on the filesystem security for the operating system that the repository is running under. The specific instructions in this section are based on traditional Unix and Linux filesystem permissions, but the principles can also be used to secure a repository running under systems with more extensive security options, such as Access Control Lists (ACLs).

CVS 1.12.2 introduced experimental support for PAM (Pluggable Authentication Modules). PAM allows system administrators to configure their choice of authentication and other security measures, rather than accepting the range of measures implemented in the application. I discuss this further in Chapter 8.

CVS's PAM support is under active development. The information in this book is correct for CVS 1.12.13, but you can expect changes if your version is later than that.

I strongly encourage you to provide feedback about PAM and CVS. The appropriate forums for this feedback are the mailing lists info-cvs@nongnu.org and bug-cvs@nongnu.org.

Sandbox security relies on the security features installed in the filesystem that the sandbox is stored on. CVS expects to find separate user and group ownership, and separate read, write, and execute permissions for files. Fortunately, these features are available in all the systems for which CVS clients are available. Sandboxes are checked out of the repository with the username of the user who creates them (with cvs checkout). If the client's computer has a group that matches the group ownership of files in the repository, files in the sandbox are stored with that group ownership.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

A CVS repository is composed of the project directories, and the special CVSROOT administrative directory. All the general CVS administrative files and configuration files are kept in CVSROOT. Most of the project-specific CVS administrative files are kept in CVSROOT as well, but there are exceptions, which are detailed next.

The project directories contain the project's files and subdirectories. The project's files are stored in RCS format and have a ,v file suffix.

Any project directory or subdirectory may contain Attic or CVS directories. An Attic subdirectory stores any file from the directory it's part of that doesn't exist on the trunk (the main development line for the file). A CVS subdirectory stores metadata for the files in its directory.

The server also stores files in a temporary directory set by either the TMPDIR environment variable or the -T command-line option. These files are under a directory called cvs-server PID, where PID is the process ID of the server. If the server is shut down and unable to clean up after itself, the files may be left in place. They can be removed safely if there is no CVS process running with the relevant process ID.

The Attic subdirectory stores files that have been removed from the trunk (the main line of development), or that were never added to the trunk. If a file exists on only one or more branches, it is kept in the Attic. Each Attic subdirectory contains files that are related to the directory the Attic is in.

CVS manages the Attic itself—you need to be conscious of it only on the rare occasions when you are editing the repository directly.

The repository contains CVS subdirectories, which contain the file fileattr, which lists the file attributes of the files in the parent directory. The file attributes are settings for the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The CVSROOT directory contains administrative files that contain information about the projects stored in CVS. The CVSROOT directory can be checked out to a sandbox, edited, and committed in the same way as any other directories or files managed by CVS.

As part of the process of committing an administrative file, CVS exports a clear-text copy into the CVSROOT directory. The CVSROOT directory contains both RCS-format repository copies of administrative files and clear-text copies of the latest revision of the files. The RCS-format files are named filename ,v. While CVS is creating the clear-text copies, it prints the message cvs commit: Rebuilding administrative file database.

Some of the files in CVSROOT allow you to run user-created scripts during the execution of CVS commands. Therefore, it's important to restrict the number of people authorized to commit or edit files in the CVSROOT directory.

It's good practice to have a specific user be the owner of the CVSROOT directory and the repository root directory, and for this user to also be the initial owner of the CVSROOT files. This practice restricts the amount of damage that can be done to these files by a malicious or careless user, unless she happens to have root permissions.

Create a group to have the group ownership of the CVSROOT directory and files, and include only trusted people in that group. If this group should be permitted to create new projects, and consists of all the people who can, it can also own the repository root directory. The CVSROOT directory and most of the files should be writable only by the repository's owner and the group, but they must be readable by all users who will be running CVS commands. The directory's SGID bit should be set, to ensure that new files are created with the same group ownership as the directory.

Two files in the CVSROOT directory should be writable by all the users who will be using the CVS commands: the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS reads some of the calling user's environment variables whenever you run a command for which the variable may affect the results. These variables, shown in the following list, are read and used by the process that runs on the repository's server. Note that these variables must be in the calling user's environment on the repository server, so different users may cause different behaviors.

CVS_SERVER_SLEEP: Delays the start of the client/server process by CVS_SERVER_SLEEP seconds to allow a debugger to be attached to it. Use this variable only when debugging the server in client/server mode.

In local-access mode, CVS uses both client and server environment variables.
CVSUMASK: Sets the default permissions of files in the repository. See "Securing Your Projects" earlier in this chapter.
PATH: Locates any programs whose paths are not coded into the CVS program. It is also used for the programs called in the scripting files. The PATH variable is less important to CVS than it was when the rcs, diff, and patch programs CVS now uses were not included with CVS.
TMPDIR: Sets the temporary directory CVS stores data in. It defaults to /tmp. CVS creates temporary files with mkstemp (BSD 4.3) if possible. It determines what is available at compile time, and if it can't find mkstemp it tries tempnam (SVID 3), mktemp (BSD 4.3), or tmpnam (POSIX), in that order. If it uses

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

A CVS repository can be backed up using the same backup tools and schedule that you use for ordinary text and binary files. You must be able to restore the repository with the same permissions and structure it had when it was backed up. You must restore the CVSROOT directory and its contents before the project directories are useful, but you can restore project root directories and their contents independently of each other.

If a file in a repository is being written to while a backup is in progress, it is possible that the file could be backed up in a state that might make it difficult for CVS to read it accurately when it is restored. For this reason, you should prevent processes from writing to the repository during a backup.

"Freezing a repository" is CVS-speak for the act of preventing users from changing the repository. The most common reason to freeze a repository is to ensure that a backup operation copies all the repository files in a consistent state.

The simplest way to freeze a repository is to block clients from accessing the CVS server. There are many ways to do this, such as shutting down the CVS server program, disallowing logins to the server system, blocking the server with a firewall rule, setting the server to single-user mode, or pulling out the network cable. Rather than blocking access to the server completely, you can use CVS's locks to read-lock the repository.

To keep the server running and allow clients to continue to read the repository files while a backup or other critical work takes place, use a script that creates lock files like CVS's internal locks. CVS honors these locks as if they were its own. Lock the directories you want to back up, make your backup, and then unlock the directories. See "Locks," later in this chapter, for a full explanation of CVS locks.

Ideally, you should write your backup script to leave out the lock files when it's backing up CVS; if you don't, you'll need to remove those locks as part of the restoration. Example 6-8 shows a script that locks an entire repository. It attempts to lock the repository and backs off if it can't lock the whole repository. The backing off is necessary to prevent deadlocks. Example 6-9 shows a script that unlocks a repository. If it can't lock the repository within nine attempts, the script backs off, reports an error, and exits. This prevents it from trying endlessly when there's a stale lock from a crashed CVS program. (See "Clearing Locks," later in this chapter, for how to fix stale locks.)

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Many CVS systems use only a single, central repository, but not all. Many open source projects that rely on CVS use mirrored repositories to distribute the latest source, and many of those have a version of the repository available on the World Wide Web. Recently, write-proxying has been enabled for mirror repositories: this process allows the user to connect to the mirror as if the mirror were the central repository.

Many project teams have public, read-only CVS repositories. If you want to do likewise, you can copy the repository, reserve the original repository for your project work, and use the copy (or mirror) repository as a public repository.

The copy can be on the same computer as the original or on a different computer or even a different network. Having two or more copies of a repository allows you to put one copy on a trusted network for your developers and another on a more public part of your network for the general public.

You can't commit to a repository mirror, but CVS permits you to make a mirror repository into a write-proxy for a primary repository. See the following section on write proxies.

Mirror a repository by copying the repository files. To avoid getting part of one release and part of another due to the copy overlapping with a commit, freeze the repository with read locks before mirroring and unfreeze it afterward.

The Unix and Linux rsync program is a useful tool to use when mirroring. It allows you to recursively transfer only the changed files between any two directories and recovers properly if it's interrupted. It also has an optional CVS-exclusion mode, called with the --cvs-exclude option, which ignores the same files CVS ignores by default. By default, rsync uses SSH, but if your system is configured differently, you can use the -e ssh option to rsync to transfer using the SSH protocol. An rsync command or script can be triggered at either the central repository or the mirror.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

There are times when you need to restructure a project or fix things up when something has gone wrong in the repository. In an ideal world, restructures or repairs would all be done using the CVS commands explained in Chapter 3 or the cvs admin command explained in Chapter 7. Sometimes, however, those commands can't do what you're trying to achieve, and you need to modify the repository directly.

The main problem with editing the repository directly is that you may lose historic data. Removing files or directories affects retrieval of older releases of a project and may affect build scripts. Moving or renaming files or directories can affect older releases, build scripts, and instructions within your files.

Always freeze a repository with write locks before hand-editing it.

Always consider backing up and freezing the directories you're hand-editing. If you're just removing a stale lock, this isn't necessary. But you should back up and freeze directories if you're moving, removing, editing, or renaming content files. Try to get your users to commit and release their sandboxes before you hand-edit the repository. They can checkout new sandboxes afterwards.

If a user does not release an old sandbox and tries to act on a filename that the sandbox has records of, but the repository does not have the file, the user will receive strange errors. Correct these errors by releasing the user's sandbox copy of the file in question and then checking out the file again using the new filename.

If you are using the scripting files in the CVSROOT directory, you may need to edit them when a directory is moved or removed.

CVS does not have a built-in command for moving or renaming a file or directory. This doesn't mean that you can't move or rename files and directories; it just means that doing so requires ingenuity.

To rename a file or directory, move it from the old name to the new name. To create a new project from parts of an older project, move the files into a directory in the repository root directory, or move a whole subdirectory into the repository root.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

A CVS sandbox is composed of a sandbox root directory, the project files and directories, and a special CVS subdirectory in the root directory and in every project directory. The sandbox root directory usually has the same name as the module it was created for, or it takes the name of the project root directory in the repository.

Project files in a sandbox are in editable form, just as if they were exported from the repository for release. The CVS subdirectory in each project directory stores metadata for the files in the project directory it is part of. This metadata is contained in a number of files (and one directory). Each of the sandbox directories may also contain a .cvsignore file.

Each project directory in a sandbox contains a subdirectory named CVS. This CVS subdirectory contains the files that store the administrative data for the files in the project directory. The following list describes the files and directories you will most likely find in a CVS directory. Files that are rarely encountered or are temporary are not included in this list. The full list of files is available in Chapter 11.

Base: Stores the pre-editing revision of any files that are being edited with cvs edit. This is a directory, not a file.
Baserev: Contains the revision information for every file in the Base directory, in the format name/revision/. Later versions of CVS may add to this format.

If you need to edit any of these files manually, back the file up before you start.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS reads the calling user's environment variables, described in the following list. The variables in the list are read and used by the process that runs on the client computer. Note that these variables must be in the calling user's environment, so different users may experience different behavior.

CVS_CLIENT_LOG: Used for debugging CVS in client/server mode. This variable should be set to a filename. If it is set, everything sent to the server is stored in the filename.in file and everything received by the client is stored in filename.out.
CVS_CLIENT_PORT: Used to set the port the client uses to connect to the CVS server in kserver, gserver, and pserver modes. By default, clients use port 2401 (gserver or pserver) or port 1999 (kserver) to connect to the server.
CVSIGNORE: A list of filename patterns—separated by whitespace—that should be ignored. See .cvsignore in the previous section.

In local-access mode, CVS uses both client and server environment variables.
CVSEDITOR or EDITOR or VISUAL: Used to set the editor CVS calls when it opens an editor for log messages. On Unix and Linux systems, this defaults to vi if these variables are unset. Using CVSEDITOR to customize CVS is preferred, as the other variables may be used by other programs as well. CVSEDITOR is searched first, then EDITOR, and VISUAL last. If the -e

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

You may at some point want to write a script that includes one or more CVS commands, such as a script to automatically export files from a repository to a web server, or a script to automatically update a test directory and attempt to build a program. If you do, you will need to know whether a given CVS command succeeded.

CVS commands set an exit status when they complete processing. A successful command always returns the success status. A failing command prints an error message and returns the failure status.

The cvs diff command behaves differently from the other commands. It returns success if it finds no differences and failure if it finds differences or encounters an error. This behavior may change in later versions of CVS.

Testing the exit status depends on the operating system. In Unix and Linux, the sh shell variable $? is 0 if CVS returns success, and nonzero if it returns a failure. Example 6-19 shows a script to test a CVS return value, and Example 6-20 shows a Windows version of the same script.

Example 6-19. Testing return values in bash


cvs commit -m "Automated commit"

if [ $? -eq 0 ]; then

        echo "Commit successful."

else

        echo "Commit failed with return code $?"

fi

Example 6-20. Testing return values in Windows


@echo off

cvs commit -m "Automated commit"

if %ERRORLEVEL% GEQ 1 goto ERR

goto OKAY

:ERR

  echo "Commit failed with return code %ERRORLEVEL%"

  goto END

:OKAY

  echo "Commit successful."

:END

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The team leader responsible for a project needs to know more about the project's tools than most other developers, or to have a team member who knows about the tools. This chapter is for the team leader and the CVS specialist on the team. It concentrates on the files and directories that make up a project and how they are stored and managed in CVS, rather than on managing the development process itself.

The topics covered include initial creation of a project's CVS files, configuring a project as a module, exporting a project, integrating CVS with build systems and bug trackers, and configuring scripts to run when certain CVS commands are used.

This chapter also covers a special type of branch called a vendor branch, and concludes with a discussion of strategies and practices for using CVS that you may find helpful.

A project is any group of files and directories that exist beneath one project root directory. Every project must include at least one directory, because CVS needs to be able to create a subdirectory to store metadata about the project.

Most often, a project represents one program, one set of related configuration files, or one web site. Sometimes, a project is a collection of related items. For instance, I store all my articles for http://www.oreillynet.com in one project, with each topic grouped under a subdirectory. Sometimes a project is a subsection of something larger.

If you want to create a project right now with default settings and minimal reading, read "Importing Projects" in Chapter 2. That section walks you through the process of importing a project.

To create a project in CVS, you need a copy of the files and directories you want to import, or an idea of which files and directories you want to make. If you are planning to import an existing project, be sure to make a backup of it before you proceed.

If you have an existing set of files and directories, check whether you have files that can be generated from other files, such as compiled code. Files that can be generated easily do not usually need to be stored in CVS and can be removed from the copy of the project. It is good practice to store the commands that generate these files in CVS as part of the project, usually as a build script or as part of the installation document.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

A project is any group of files and directories that exist beneath one project root directory. Every project must include at least one directory, because CVS needs to be able to create a subdirectory to store metadata about the project.

Most often, a project represents one program, one set of related configuration files, or one web site. Sometimes, a project is a collection of related items. For instance, I store all my articles for http://www.oreillynet.com in one project, with each topic grouped under a subdirectory. Sometimes a project is a subsection of something larger.

If you want to create a project right now with default settings and minimal reading, read "Importing Projects" in Chapter 2. That section walks you through the process of importing a project.

To create a project in CVS, you need a copy of the files and directories you want to import, or an idea of which files and directories you want to make. If you are planning to import an existing project, be sure to make a backup of it before you proceed.

If you have an existing set of files and directories, check whether you have files that can be generated from other files, such as compiled code. Files that can be generated easily do not usually need to be stored in CVS and can be removed from the copy of the project. It is good practice to store the commands that generate these files in CVS as part of the project, usually as a build script or as part of the installation document.

If you have a set of files stored in another version control system and want to save their revision history, see "Importing from Other Version Control Systems" later in this chapter. If you don't need to retain their revision history, export the files from the other system using a command that gives you a clean copy of the project with no administrative files, and use that copy to import from.

If you don't have any existing files, you can import a single directory with the project name. If you are more comfortable with a structure to work from, create an initial directory structure for your project and import that.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

All project leads need to distribute completed work at various stages of a project. When working with some projects, such as content management of web sites, you need to distribute files frequently with small changes. With others, such as large programming projects, you need to distribute files less often and with larger changes.

One way to distribute files is to use the cvs checkout command to produce a set of files for distribution. Another way is to use the cvs update command on an existing set of files.

The checkout and update commands are designed to produce a sandbox suitable for editing the files being checked out or updated. The commands create administrative files in the sandbox that most project leads don't want in a public distribution, so you may need to remove the administrative files in the CVS subdirectory from each of the checked-out directories.

There is a benefit to using checkout and update to distribute files. When you use either command on an existing sandbox, CVS sends only the differences between the revisions currently in the sandbox and the revisions requested from the repository. This approach uses less bandwidth than the export command, which retrieves entire files.

Although cvs checkout creates a sandbox suitable for editing copies of a project's files, cvs export creates a release of the project's files that is suitable for publication. This command uses most of the same internal code as cvs checkout, but cvs export does not create any CVS subdirectories or CVS administrative files.

cvs export requires that you use a date or tag command option. The -D now or -r HEAD options export the latest revisions of all files in a project.

If you don't have any binary files in your project, you can export with -kv to set the keyword-substitution mode to values only, so that the string $keyword:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

In the repository's CVSROOT directory, there are several scripting files that allow you to run scripts while a project is being committed, tagged, updated, or modified in other ways. The scripts called from scripting files are often used to interact with other programs or to enforce standards.

The CVSROOT directory and its files were described in Chapter 6. This section explains the scripting files in more detail.

Example 7-6 shows a commitinfo scripting file that runs a layout-testing program called indent-tester on the wizzard project files. CVS calls scripts in commitinfo before files are committed.

Example 7-6. Sample commitinfo file


^wizzard/src\(/\|$\) /var/lib/cvs/CVSROOT/indent-tester -gnu %r/%p %s

To make Example 7-6 work with CVS versions prior to 1.12.6, remove the %r/%p %s.

When a project file is committed, CVS searches the commitinfo file for rules that match the project file's path; if CVS finds a rule, it runs the script given in that rule. The rule in Example 7-6 matches all files in the src directory (and its subdirectories) of the wizzard project and tells CVS to run the indent-tester script on those files, also providing the parameters the script expects. (Later in this chapter, Example 7-8 shows the indent-tester script that can be used to enforce indentation standards for a project.)

CVS processes the scripting files separately for each directory that is affected by a command, and it calls the script in the scripting file once for each directory it matches. If you run cvs commit wizzard, CVS checks commitinfo for patterns that match wizzard and runs the script once for the files in the wizzard directory, then does the same for each subdirectory, checking for patterns that match wizzard/doc and processing its files, followed by wizzard/lib and wizzard/src.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS is rarely used alone. There are a number of project-management tools available, each used to perform a different set of tasks. The scripting files can be used to connect CVS to other project-management tools, such as bug trackers and build scripts.

Interfacing with a bug tracker is easiest if the tracker accepts input from standard input or via an email form. Use the rcsinfo file to have the cvs commit editor screen include the template your bug tracker requires, and use the verifymsg file to ensure that all fields are filled in appropriately. Then have a script in verifymsg or loginfo mail the log data to your bug tracker.

Examples 7-11 and 7-12 show how to integrate with the Bugzilla bug-tracking tool, available at http://bugzilla.mozilla.org. These examples assume that the Bugzilla email gateway has been enabled. The @resolution field in the message template allows you to change a project's status and is supported directly by Bugzilla.

Use the verifymsg script in Example 7-11 to separate out the bug ID so it can be used in the mail subject (which must have the format [Bug XXXX]). The rest of the log message can be sent as the mail body. The script uses the read command to get the bug ID from the first line of the log message, checks that the first line it reads uses the format it expects, and then mails the bug ID and the rest of the stdin input to the user bugzilla on the same computer. The script returns 1 if the format was wrong and 0 if it succeeds in mailing everything to Bugzilla.

Example 7-11. Interfacing with Bugzilla, verifymsg


#! /bin/bash

read prompt bugid

if [ $prompt != '@bugid' ]; then

     return 1

else

     mail -s "[Bug $bugid]" bugzilla

fi

return 0

Example 7-12 shows an rcsinfo template file that contains the @bugid string that Example 7-11 expects and the @resolution

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Project administrators should be aware of the CVS commands described in Chapters 3 and 5. You may also want to read Chapters 4 and 6.

In addition to the commands described in those chapters, there are two commands that are particularly useful to project administrators: cvs admin and cvs history. cvs admin allows you to use RCS-like commands on files stored in the repository. cvs history provides a record of the actions performed on a project's files and is similar to cvs log or cvs annotate.

The cvs admin command is used to edit the RCS files directly in the repository. It is more accurately thought of as a set of commands than a single command, as it provides many of the commands that RCS would make available, though not all of these commands are usable or have an effect that matters to CVS. These commands are present mostly for historic reasons and backward compatibility with early versions of CVS.

If there is a system group called cvsadmin on the repository server, only users in that group can use the cvs admin command. If this group does not exist, any user can use the cvs admin commands on any repository files they have permission to change. Consider using the cvsadmin system group, as some of the cvs admin commands can prevent CVS from using the affected file or files.

There is a new option in the config file of CVS 1.12.1 and later. The UserAdminCommands option allows the system administrator to set cvs admin options that users who are not in the cvsadmin group can run.

The syntax for cvs admin is as follows:


cvs [cvs-options] admin command-options [filename...]

I strongly recommend always stating the filenames that you wish cvs admin to act on, as some of the cvs admin commands can be difficult or impossible to recover from if you accidentally apply them to the wrong file. If you do not specify a filename,

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS is a tool that can help you manage a project, but you need to decide how to use CVS with your project to make it work effectively for you and your team. The following sections present some ideas to help you integrate CVS into your working practices.

Decide whether and how you will use tags and branches, and then decide on the format to use for tag and branch names. Branching philosophies, styles, and policies are explained in the "Branching Strategies" section of Chapter 4.

I strongly recommend keeping almost-complete work separate from experimental work. In programming projects, I recommend keeping bug fixes separated from the main body of development by putting either bug corrections or development on a branch.

If you use branches, designate an owner for each branch. The owner should be responsible for seeing that the branch is used for its specified purpose, for maintaining a record of the changes made to that branch, and for managing merges to or from that branch.

I strongly recommend tagging at strategic points in development, at the root of each branch, and at each merge point. See "Tagging Strategies" in Chapter 4 for more suggestions on tagging.

Automation can be helpful in ensuring that a project moves smoothly to completion. Generally, automation translates into consistency. When using CVS on a project, you may find the following automation strategies to be helpful:

Use the scripting files in CVSROOT to enforce project standards and assist project communication.
Automate builds to encourage projects to be tested frequently. This practice also ensures that the entire build process is recorded and performed correctly every time.
Integrate CVS to your change-tracking program in order to minimize the effort developers have to put in to do both version control and change tracking.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Most projects involve a remote repository (one that's on a different machine than the clients). This chapter discusses remote repositories, access methods, how to set up each access method, and security considerations for each type of access.

This chapter also discusses the two access methods for local repositories: local and fork. The fork method presents a way to access a local repository as if it were a remote repository.

CVS can operate equally well as a single program that handles both the sandbox and the repository or as a pair of programs—a client managing the sandbox and a server managing the repository.

CVS can run as a single program if both sandbox and repository are on the same computer, or if the repository is on a file server and the computer that the sandbox is on perceives the shared directories as local.

If you have a personal repository for private work, you may choose to keep the repository on the same computer as your sandbox. If you are sharing a server with several other people, you may have a shared repository on the same server as your sandboxes. In such situations, be particularly careful to back up the repository. When the repository and the sandbox are on different computers, each acts as a partial backup of the other. When they are on the same computer, that inherent backup is not available.

Whenever CVS runs a command from a client, it needs to know where to find the CVS repository. The address of the repository is called the repository path. CVS looks for repository paths in the sandbox, the CVSROOT environment variable, and the -d repository_path command option.

If you run a CVS command from within a sandbox, CVS uses the repository path that is stored in the sandbox. When a sandbox is not available—such as when you're creating a sandbox or issuing a command from outside a sandbox—you must specify which repository you are attempting to access. You also need to specify the repository path if you are in a sandbox but wish to access a different repository than the one the sandbox uses.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Whenever CVS runs a command from a client, it needs to know where to find the CVS repository. The address of the repository is called the repository path. CVS looks for repository paths in the sandbox, the CVSROOT environment variable, and the -d repository_path command option.

If you run a CVS command from within a sandbox, CVS uses the repository path that is stored in the sandbox. When a sandbox is not available—such as when you're creating a sandbox or issuing a command from outside a sandbox—you must specify which repository you are attempting to access. You also need to specify the repository path if you are in a sandbox but wish to access a different repository than the one the sandbox uses.

You can specify a repository path from the command line with the -d repository_path option, or you can specify it with the CVSROOT environment variable. CVS uses the path given with the -d option in preference to the path in the sandbox, and it uses either the sandbox or the -d path in preference to the path in the environment variable.

The rtag, rlog, rdiff, rannotate, and export commands can run without a sandbox. If these commands are run outside a sandbox, they need either the -d option or the CVSROOT environment variable.

The format for a repository path is:


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

The method can be one of the following:

local: For the local machine
ext: For externally defined rsh or rsh-like connection methods (such as SSH)
fork

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

In version 1.12.7, CVS added two options to the connection methods: the proxy and proxyport methods that permit a client to connect to a server via an HTTP proxy. In 1.12.11, three other options were added (CVS_RSH, CVS_SERVER, and Redirect).

Options are included in the method section of a repository path. The repository path without options is usually something similar to the following:


:ext:cvs_server:/var/local/cvs

The repository path with an option would look like this:


:ext;CVS_RSH=/bin/ssh:cvs_server:/var/local/cvs

It's possible to use multiple options in the same repository path. To do this, chain them with semicolons:


:ext;CVS_RSH=/bin/ssh;CVS_SERVER=/bin/cvs;Redirect=false:cvs_server:/var/local/cvs

The binaries for cvs and ssh are more likely to be found under /usr or /opt than /bin. I thought that using /usr/local/bin/cvs or /opt/cvs-1.12.13/bin/cvs made the examples awkward. Those are, however, more likely places to find the commands.

The methods are:

CVS_RSH= path: This method allows you to declare your rsh replacement command on the command line, instead of as an environment variable. It overrides the CVS_RSH environment variable. Most of the time, this will be ssh. See "The ext and server Access Methods," later in this chapter, for an explanation of the rsh replacement.

This option is valid only with the ext method, and was added in 1.12.11.
CVS_SERVER= path: This method allows you to declare the server program you wish to use on the command line, instead of as an environment variable. It overrides the CVS_SERVER environment variable. In most cases, neither this nor the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

If your repository is on the same computer as your sandbox (or the sandbox you want to make) or on a shared filesystem that is accessed as if it were a local partition, you can use the local method to access the repository.

For the local access method, the repository path format is:


[:local:]/path

When running a command that requires an explicit path declaration, put the repository path in your CVSROOT environment variable or use the path as the argument to the -d repository_path option. You will most likely need this path declaration when creating a sandbox, but it is also necessary for cvs export and cvs rtag.

If you just enter the directory path with no hostname or method declaration, CVS uses the local access method.

With local access, CVS does not run in client/server mode. One program manages both the sandbox and the repository. The program runs under the username that it was called with, and it has the access permissions of that user. Any programs that CVS calls (such as programs called from a scripting file) run with the same username and access permissions.

If local access mode is being used on a single-user computer, security normally is not an issue. On shared filesystems or servers, your repository security problems are the same as the usual security issues for file sharing. Use the security services of your operating system to secure a shared repository that is accessed with the local method.

Example 8-1 shows how to check out a sandbox using the local access method.

Example 8-1. Using the local access method


jenn@helit:/tmp$ cvs -d :local:/var/lib/cvs checkout wizzard

cvs checkout: Updating wizzard

U wizzard/Changelog

U wizzard/INSTALL

U wizzard/Makefile

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

In my experience, ext is the most commonly used access method, and it is usually used with SSH. ext stands for external, which refers to an external (to CVS) rsh or remote shell program. This method uses a remote shell program to connect the sandbox client computer to the repository server computer. The server method is almost the same as the ext method. The only difference is that server uses a remote shell program that is included with CVS.

To use a program other than rsh with the ext connection method, the CVS_RSH environment variable on the client should be set to the name of the program and the directory containing the program should be in the user's PATH on the client computer. Alternatively, you can set the CVS_RSH environment variable to the absolute path to the program without modifying the PATH variable. You may also use the CVS_RSH method option, described in "Method Options" earlier in this chapter.

ext accepts any command-line-based program that can be called with the following syntax:


program [-b] [-l username] host commands

The program must run the commands in a remote shell and pipe standard input (stdin) and standard output (stdout) without filtering the content. The -b is necessary only if the program is running on OS/2 and is used to force rsh to run in binary mode, without end-of-file conversion. The -l username is used (by CVS) only if there is a username included in the repository path.

For the ext access method, the repository path format is:


[:ext:][user@]hostname[:]/path

The user needs a username on both the client computer and the server computer. If these names are the same, the user@ part of the repository path isn't needed. In versions of CVS prior to 1.11.1, the colon between hostname and path was required.

The user's PATH environment variable on the server must include the directory that contains the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The fork access method acts like ext without the external connection. You can use it only when the repository and the sandbox are on the same computer. fork makes CVS run in client/server mode and is most useful for debugging—to isolate whether a fault is in CVS's remote protocols or in the networking—but it is also used as a substitute for the local method.

The fork method uses the CVS_SERVER environment variable, as described in "The ext and server Access Methods," earlier in this chapter.

The repository path format for fork is:


[:fork:]/path

With the fork access method, both client and server programs run under the username that the client was called with and have the filesystem access of that user. Any programs that CVS calls (such as programs called from a scripting file) run with the same username and access.

Security normally is not an issue with the fork access method if the method is used on a single-user computer. However, be aware of the security issues of shared filesystems or shared servers; use the security services of your operating system to secure a shared repository that is accessed with the fork method.

Example 8-7 shows how to check out a sandbox using the fork access method.

Example 8-7. Using the fork access method


jenn@helit:/tmp$ cvs -d :fork:/var/lib/cvs checkout wizzard

cvs server: Updating wizzard

U wizzard/Changelog

U wizzard/INSTALL

U wizzard/Makefile

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The gserver access method uses the GSS-API (Generic Security Service Application Programming Interface) to support authentication and encryption of the CVS connection. The GSS-API in itself does not authenticate or encrypt the connection; these processes are performed by an authentication or encryption system configured to work with the GSS-API. The most common system used with the GSS-API is Kerberos 5.

The GSS-API is explained in RFC 2743, available at http://www.ietf.org/rfc/rfc2743.txt. RFC 1964 explains how the GSS-API interacts with Kerberos 5. To use Kerberos 5 with CVS, use the GSS-API and the gserver access method. Kerberos 4 is used with the kserver access mode, explained in the next section.

The repository path format for the GSS-API is:


:gserver:[user@]hostname[:[port]]/path

The default port for gserver is 2401. If user is not specified, the client sends the username of the calling user on the client computer.

The CVS client and server must both be compiled to run the GSS-API. If you intend to encrypt the data stream, you also need to have encryption enabled at compile time. You can test whether your CVS program has the GSS-API compiled by attempting to check out a sandbox. Example 8-8 shows the result when CVS does not support the GSS-API.

Example 8-8. Testing for gserver mode


bash-2.05a$ cvs -d :gserver:cvs_server:/var/lib/cvs checkout wizzard

cvs checkout: CVSROOT is set for a GSS-API access method but your

cvs checkout: CVS executable doesn't support it.

cvs [checkout aborted]: Bad CVSROOT: ':gserver:cvs_server:/var/lib/cvs'.

You can test for encryption support by checking the options list, as shown in Example 8-9.

Example 8-9. Checking for encryption


bash-2.05a$ cvs --help-options

CVS global options (specified before the command name) are:

.

.

.

    -x           Encrypt all net traffic.

.

.

.

(Specify the —help option for a list of other help options)

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The kserver method is used to connect using Kerberos 4. If you do not have an existing Kerberos 4 installation on your CVS repository server, I recommend you use Kerberos 5, described in the preceding section. Kerberos 4 has known weaknesses that Kerberos 5 resolves. This section assumes that you have an existing Kerberos 4 installation and the documentation to configure and use it.

Kerberos 4 is a reasonably secure authentication system, but it has known flaws. Kerberos 5 fixes some of them; most critically, it prevents a replay attack. In Kerberos 4, there is a five-minute window in which an attacker can sniff an authentication request, modify and resend it, and get an authentication ticket. Kerberos 5 allows only one ticket to be produced per request.

The repository path format for Kerberos is:


:kserver:[user@]hostname[:[port]]/path

The default port for kserver is 1999. If user is not specified, the client sends the username of the calling user on the client computer.

The CVS client and server must both be compiled to run Kerberos 4. If you intend to encrypt the data stream, you also need to have encryption enabled at compile time. You can test whether your CVS program has compiled kserver support by checking the command list, as shown in Example 8-11.

Example 8-11. Testing for kserver mode


bash-2.05a$ cvs --help-commands

CVS commands are:

.

.

.

        kserver      Kerberos server mode

.

.

.

(Specify the --help option for a list of other help options)

You can test for encryption support by checking the options list, as shown earlier in Example 8-9.

To use CVS with kserver, install and configure Kerberos 4 as described in your Kerberos manual. You need to have the header files for Kerberos 4 available for CVS to link to. The principal name for CVS is cvs.

To recompile CVS to support Kerberos 4, follow the instructions in Chapter 2 on installing from source. Use the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The pserver method allows users to connect to the repository with a username and password that are stored on the repository server. The main advantage of pserver is that it permits anonymous, passwordless, read-only access. The main disadvantages of pserver mode are that it uses a trivial encoding scheme for passwords and the data stream is not encrypted. pserver mode is included in CVS automatically, but it requires a password file that needs to be configured.

To use pserver, you need a username on the repository computer, to enable CVS to run programs on that computer. You may share this username (your system username) with other users and have a separate CVS username to identify you to CVS as an individual. You also need to log in before running other commands.

To support the pserver access method, CVS needs to run a server on the computer that hosts the repository. To configure the repository to run the CVS server, edit inetd.conf and add cvs pserver. See "Using inetd with gserver, kserver, and pserver" later in this chapter for more information on inetd configuration.

The repository path format for pserver is:


:pserver:[[user][:password]@][hostname:[port]]/path

The default port for pserver is 2401. If the user is not specified, the client sends the username of the calling user on the client computer.

You need to configure the passwd file and possibly the readers and writers files before you can use pserver. These files are explained in "The passwd File" and "The readers and writers Files" later in this chapter. You also need to use the login command, explained in "login and logout."

You can bypass the passwd file by using the SystemAuth configuration option in the config file (explained in Chapter 6).

If you bypass the passwd file using SystemAuth, CVS uses the shell account passwords for your users with the minimal security it uses for pserver passwords. Be sure that you take the security risks into account if you choose to do this.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

gserver, kserver, and pserver access modes require a server to run on the repository computer. For these modes, the server is started with inetd or xinetd .inetd is configured in the "Other services" section of /etc/inetd.conf, as shown in Examples 8-18 and 8-19. Note that the configuration must be all on one line. After you edit inetd.conf, you should send it a HUP signal, as in killall -HUP inetd.

Example 8-18. Inetd for gserver and pserver


#:OTHER: Other services

2401 stream tcp nowait root /usr/bin/cvs cvs -f --allow-root=/var/lib/cvs pserver

Example 8-19. Inetd for kserver


#:OTHER: Other services

1999 stream tcp nowait root /usr/bin/cvs cvs -f --allow-root=/var/lib/cvsroot kserver

The gserver access method connects to a pserver CVS server. The code that runs the server end of pserver checks whether it has been connected to with the pserver or gserver access method and runs the appropriate server code.

The parameter to the --allow-root option is the path to the repository root directory. If there will be several different repository root directories, add more --allow-root options. If inetd complains about the line length or command length, have inetd call a script which runs CVS with the appropriate options.

You can use the -T option or the TMPDIR environment variable to set a specific temporary directory. If no directory is listed, /tmp is used.

It can be useful to run the server as a special user, possibly named cvs, to limit the amount of damage that can be done if one of the arbitrary scripts (or CVS itself) is insecure. If you do this, ensure that the repository root directory and the CVSROOT files start out being owned by the cvs user, and make sure that the cvs user is in all the groups that can use the repository. You also need to ensure that all users run as user

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

PAM (Pluggable Authentication Modules) provides an interface that programs can use to connect to whatever authentication methods are desired. Authentication can be as trivial as the user typing "hello world", as complex as biometrics, or as prosaic as passwords. I think PAM is a great boon for system administrators, and I'm excited to see it in CVS.

PAM works by having the system administrator define which modules she wants run for each application. The application calls PAM, PAM checks its configuration files, and then PAM calls the relevant modules. If the module requires additional data (such as a password), the module requests it from PAM, and PAM requests it from the application, then hands it to the module. The module runs, and reports its results to PAM.

PAM combines the results of all the modules it's configured to run for the application, and then returns a single combined success or failure to the application, depending on a strict set of criteria. The criteria are also configured by the system administrator.

At the moment, PAM support in CVS is experimental, and is limited to the fallback option in the pserver connection method. To get PAM support for CVS, configure your CVS executable with --enable-pam, having SystemAuth set to yes in your CVSROOT/config file, and leave CVSROOT/passwd empty.

My article "Introduction to PAM" explains how to configure PAM on your system, and it is available at http://www.linuxdevcenter.com/pub/a/linux/2001/09/27/pamintro.html.

The default PAM configuration file for CVS is /etc/pam.d/cvs. If your version of PAM uses a single /etc/pam.conf file instead of a separate file for each application, the application name is cvs. The PAM application name (or configuration file name) can be configured at compilation time with -with-hardcoded-pam-service-name=name. Use ./configure to set the PAM compilation options. Make sure you read the INSTALL file in the CVS source code, and the installation instructions in Chapter 2.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

It would be nice if CVS were perfect, but it isn't. There are times when CVS doesn't work as expected, but with the techniques and information in this chapter, you should be able to fix the most common problems.

Most of the CVS error messages are helpful but concise. They usually tell you what is wrong and may contain key words or phrases that lead you toward a resolution to the problem. Few of the error messages actually provide a resolution, however, because usually there are several possible causes of any given problem.

If your problem seems to be confined to a single sandbox, the simplest solution is usually to check out a new sandbox. To save changed files, copy them to the new sandbox before erasing the old sandbox. (If the new sandbox has newer revisions of some files, don't copy over them.)

To fix problems in a single sandbox directory, check the sandbox administrative files in the CVS subdirectory. If a command has been aborted, the administrative files may have been partially changed. Chapter 6 explains the sandbox administrative files.

Many repository problems are caused by permissions errors. If a user (system username) can't read the repository and the problem doesn't seem to be a networking issue, check the repository permissions. The username of the user must be a member of a group with access to the files that they're trying to read. Thankfully, permissions problems are easy to fix. Chapter 6 covers permissions in detail.

CVS is an open source software program that was created by a group of programmers, rather than by a specific company. Because there is no company that created CVS—which means that there is no company that gains revenue from selling it—there is no official source of commercial support. Companies in many parts of the world provide high-quality commercial support for open source products. CVS is a widely used version control system, so most of these companies have staff who are familiar with CVS.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Most of the CVS error messages are helpful but concise. They usually tell you what is wrong and may contain key words or phrases that lead you toward a resolution to the problem. Few of the error messages actually provide a resolution, however, because usually there are several possible causes of any given problem.

If your problem seems to be confined to a single sandbox, the simplest solution is usually to check out a new sandbox. To save changed files, copy them to the new sandbox before erasing the old sandbox. (If the new sandbox has newer revisions of some files, don't copy over them.)

To fix problems in a single sandbox directory, check the sandbox administrative files in the CVS subdirectory. If a command has been aborted, the administrative files may have been partially changed. Chapter 6 explains the sandbox administrative files.

Many repository problems are caused by permissions errors. If a user (system username) can't read the repository and the problem doesn't seem to be a networking issue, check the repository permissions. The username of the user must be a member of a group with access to the files that they're trying to read. Thankfully, permissions problems are easy to fix. Chapter 6 covers permissions in detail.

CVS is an open source software program that was created by a group of programmers, rather than by a specific company. Because there is no company that created CVS—which means that there is no company that gains revenue from selling it—there is no official source of commercial support. Companies in many parts of the world provide high-quality commercial support for open source products. CVS is a widely used version control system, so most of these companies have staff who are familiar with CVS.

See the CVS wiki at http://ximbiot.com/cvs/wiki/ and http://ximbiot.com/cvs/wiki/index.php?title=Commercial_Support

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

If you are having difficulty connecting to a repository, first confirm that the repository path is declared correctly. The most common mistake when checking out a new sandbox is to forget to specify the repository path at all. Another common mistake is to forget to specify the connection method if you are using a method other than local or ext.

If you want to examine the data sent to or received from the server, set the CVS_CLIENT_LOG environment variable to a filename. It must be set on the client computer, and the traffic is logged in files in the current working directory named for that filename, with the suffixes .in and .out. For instance, if you set CVS_CLIENT_LOG to cvslog, the traffic is logged to cvslog.in and cvslog.out. (Traffic to the server is logged to cvslog.in, and traffic from the server is logged to cvslog.out.)

The gserver, kserver, and pserver connection methods rely on a server that is started with inetd. inetd sets a limit on the number of connections per unit of time and delays further connections. If you expect heavy use of CVS, you may need to configure inetd to accept more connections per minute. Not doing so may cause "connection refused" error messages.

If you're having trouble with the write proxy system, the most likely cause is the client being an older client and the server not being configured correctly to support it. See Chapter 6 for the configuration information.

If you are in an active sandbox and are receiving an error like the one shown in Example 9-2, the Root or Repository file in the CVS subdirectory of the current sandbox directory has become unreadable. Chapter 6 includes an explanation of these files and what they should contain, but the simplest way to correct a problem in a sandbox is to remove and recreate the sandbox. If there are changes in the sandbox files, be sure to preserve them before removing the sandbox.

Example 9-2. Repository undeclared

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS reserves some filenames for its own uses, and other filenames are included in the default ignore list.

If you have a file that CVS appears to be ignoring, check the default ignore list and any cvsignore files in your repository, home directory, or sandbox. The default list is provided in "cvsignore" of Chapter 6. If the -I! option to a CVS command causes CVS to recognize the file, then you can be sure the file is in a cvsignore list. You can temporarily force CVS to recognize an ignored file by stating it explicitly as a command parameter.

CVS uses CVS and Attic directories in the repository. CVS prevents you from using the filename CVS but permits you to create files or directories called Attic. If you use an Attic directory and look in the repository, the Attic directory has files that don't exist on the trunk from the directory above it, as well as those you are currently using in your sandbox version of the Attic. You should avoid using Attic as a file or directory name.

CVS may ignore a filename with a # or .# prefix, as CVS reserves some files with the prefix .# for its own use. In the sandbox, CVS uses the .# prefix for copies of files it has overwritten during a merge. In the repository, lock files start with #.

Another cause of filename problems is a conflict between the filesystem on a client computer and the filesystem on a repository. For example, filename case is significant in Linux and Unix filesystems, but not in Windows filesystems, and the significance of filename case varies in Macintoshes—depending on which filesystem they're using, and on a configuration option. If two filenames vary only in case and you are checking them out to a filesystem that ignores case, the second file to be checked out may overwrite the first. This action can also cause problems when you attempt to change the case of a file in Windows. Another possible case-related problem is that if you are disconnected from the network, on an operating system that doesn't consider case relevant, then you

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

If CVS is reporting lines as longer or shorter than they should be, there may be a problem with the line-ending conversion from one filesystem to another.

If you are using the ext access method with an rsh replacement, your replacement may be trying to convert line endings. CVS relies on being able to do the conversion itself.

If this is not the problem and the file in question is a text file, you might have binary keyword-expansion mode set for the file. Use the command cvs status filename to show the keyword-expansion mode, and use cvs admin -kkv filename to fix the file in the repository by setting its keyword-expansion mode to the default for text files. If a binary file is corrupted, it might be set as a text file. The command cvs admin -kb filename sets the binary file's keyword-expansion mode correctly, but it might not repair the damage to the local file. To retrieve the original version of the file, use cvs update -r 1.1 -p > filename.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

For all access methods except pserver, CVS relies exclusively on the filesystem to manage permissions. Each user must have a username on the repository server, and must have write access to every directory that contains files they will need to commit.

You can control permissions only at a directory level. If a user will need to commit to any file in a directory, she needs read and write access to the whole directory.

Once, I was working on a project where I had to connect to the repository server through an intermediate proxy server. We kept getting permission errors and eventually tracked it to the intermediary. We all had membership in the col group on the client and repository servers, but not on the intermediary. As files passed through the intermediate server, their group membership information was lost, so they were saved in the repository with no group ownership. We corrected this by setting the repository directories' SGID flags on the repository server.

The history and val-tags files in the repository's CVSROOT directory must be writable to all CVS users. The history file can be removed if none of your users use the cvs history command.

The pserver connection method uses a more complicated permission system than the one other connection methods use. The passwd file in the repository's CVSROOT directory can cause a user to have two effective usernames: one that affects only CVS and another that affects the filesystem. If a user has permission within one but not the other, he may be unable to access his project files. For instance, if his CVS username is in the writers file in the CVSROOT directory, CVS attempts to allow him to write to his project files. If, however, his system username is not allowed to write to the project directories, the operating system denies access and CVS is unable to write to the files.

The readers and writers files in the repository's CVSROOT directory set read-only or read-write permission based the on CVS username. These files must have a newline character after each username, including the last.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS removes its lock files when a CVS process completes properly, but processes that are killed can sometimes leave lock files in place. Chapter 6 explains the process of removing lock files and provides an example of the messages CVS displays when a lock file is present.

If you have to wait for valid lock files frequently, you may need to reduce the length of time a lock file is active in the repository. Locks are based on the directory that is being locked, so if you have frequently accessed project directories with many files or large files, you may benefit from splitting them into smaller directories.

If you are waiting for lock files frequently, you can also check whether your system is being overloaded. You may have network trouble, or large checkouts or commits may be overloading your system memory or swap space. Check the load average on the repository server, and find out what the CPU is doing. If you have insufficient memory, your server will be spending a lot of time swapping. You might also experience delays due to slow hard drive access times.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The most common cause of CVS timing problems is a mismatch in the time settings of the server and the client. Ideally, both server and client should maintain their base time clock in UTC and convert to local time for display. Having one (or both) maintaining their base time clock in local time is acceptable, provided that the machine is configured to know that it's maintaining local time.

Trouble comes if one or both is maintaining local time but thinks that it's maintaining UTC, or if the two machines disagree on what time it is. Fortunately, NTP (network time protocol) can ensure the machines keep the same time, and modern operating systems make time configuration easy.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

This chapter is a comprehensive reference of all CVS commands, with a brief summary of what each does. It is intended to be useful as a quick reference, not a tutorial.

If you have never used CVS before, read Chapter 2 or Chapter 3 before reading this reference. Those chapters explain the basic concepts of CVS and how to use it effectively.

CVS supports a number of command-line options that you can use to control various aspects of CVS behavior. Command-specific options are described in "CVS Commands," later in this chapter. This section focuses on options that you pass to the cvs executable itself, not to any specific CVS command.

The syntax of any CVS command is as follows:


cvs [cvs-options] [command] [command-options-and-arguments]

The specific cvs-options modify the behavior of the main CVS code, rather than the code for a specific command. The following options are valid:

-a: Authenticate all network traffic. Without this option, the initial connection for the command is authenticated, but later traffic along the same data stream is assumed to be from the same source.

This option is available only with GSS-API connections. (If you use ssh as your rsh replacement in the ext connection mode, ssh authenticates the data stream, and you don't need extra authentication.)

Support (in the client) for this option is generated when CVS is compiled. You can test whether your installation supports -a by checking whether it is listed in cvs --help-options. The command-line client can be compiled to support it by using the --enable-client option to the configure script.

The server always supports -a. See also -x.
--allow-root= directory

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS supports a number of command-line options that you can use to control various aspects of CVS behavior. Command-specific options are described in "CVS Commands," later in this chapter. This section focuses on options that you pass to the cvs executable itself, not to any specific CVS command.

The syntax of any CVS command is as follows:


cvs [cvs-options] [command] [command-options-and-arguments]

The specific cvs-options modify the behavior of the main CVS code, rather than the code for a specific command. The following options are valid:

-a: Authenticate all network traffic. Without this option, the initial connection for the command is authenticated, but later traffic along the same data stream is assumed to be from the same source.

This option is available only with GSS-API connections. (If you use ssh as your rsh replacement in the ext connection mode, ssh authenticates the data stream, and you don't need extra authentication.)

Support (in the client) for this option is generated when CVS is compiled. You can test whether your installation supports -a by checking whether it is listed in cvs --help-options. The command-line client can be compiled to support it by using the --enable-client option to the configure script.

The server always supports -a. See also -x.
--allow-root= directory: Used as part of the inetd command string for server, kserver, and pserver connection methods. The directory is the repository root directory that the server allows connections to. Using --allow-root more than once in a command allows users to connect to any of the specified repositories.

This option is only relevant when configuring the CVS server, so if you're not a server administrator, you can safely ignore it. (If you are a server administrator, see Chapter 8 for more information.)

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Most of your interaction with CVS is through the various CVS commands. Even if you use a graphical client, most of the functions the client uses call the CVS commands.

Most commands have a shortened nickname that you can type instead of the longer command name. These are called command synonyms in CVS jargon.

Synonyms: ad, new

cvs [cvs-options] add [-k mode] [-m message] files

Adds a file or directory to the repository. This command can also be used to undo an uncommitted file deletion or to restore a deleted file. A file that is added with this command is not uploaded to the repository until the next cvs commit. A directory is added immediately (unless you are using a client with an "offline" mode, and are offline).

Section 10.2.1.1: Command options

-k mode: Add a file or files with the designated keyword-expansion mode. This option also sets the default keyword mode for the file. If you forget to set the default keyword mode when you cvs add a file, you can do so later with cvs admin, unless the repository administrator has limited the users of cvs admin.

The keyword-expansion modes are listed in "Keywords and Keyword Modes" of Chapter 11 and are explained in "Keywords" in Chapter 3.
-m message: Use the specified message as the description of the newly added file. The description is shown in cvs log output.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

This chapter is a comprehensive reference of CVS topics other than commands. It is intended to be useful as a quick reference, not a tutorial.

If you have never used CVS before, I suggest you read Chapters 2 and 3 before reading this reference. Those chapters explain the basic concepts of CVS and how to use it effectively.

This chapter contains the following sections:

"Administrative Files": Describes CVS administrative files in the sandbox on the client computer or in the user's home directory on the server.
"CVSROOT Files": Describes CVS administrative files in the repository's CVSROOT directory.
"CVSROOT Variables": Describes variables that you can use in the administrative files in the CVSROOT directory.
"Dates": Describes date and time formats that you can use with CVS.
"Environment Variables": Describes environment variables on the server or the client that affect CVS.
"Keywords and Keyword Modes": Describes the keywords that CVS uses, the expansion modes that affect how CVS processes the keywords, and how CVS processes line endings.
"Pattern Matching": Describes regular expression and wildcard pattern matching in CVS.
"Repository Access Methods": Describes methods used to access local and remote CVS repositories.

CVS needs to keep track of what it's doing, so it maintains a number of administrative files. Most of the files are in the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS needs to keep track of what it's doing, so it maintains a number of administrative files. Most of the files are in the CVS subdirectory of each sandbox directory, but there may also be hidden files in the directory itself, with filenames that start with a dot (.). In addition, the user's home directory can contain CVS administrative files that affect all of that user's sandboxes; these filenames are also prefixed with a dot.

In client/server mode, all the dot files other than .rhosts should be on the client computer. The .rhosts file should be in the user's home directory on the server computer.

These are the dot files in the sandbox directory:

.cvsignore: Contains a list of files CVS should not process. This file uses the same format as cvsignore in the repository's CVSROOT directory and may be checked into CVS. See Chapter 6 for more information.
.#filename.revision: CVS is built on the philosophy of never fully losing data. So if you get an update that overwrites a project file, and the file is not synchronized with the repository, the original file is stored as .# filename . revision, where revision is the BASE revision of the file. This way the changes you haven't saved in the repository are not lost.

These are the dot files in a user's home directory:

.cvsrc: Contains a list of CVS commands and the options the user wants as default options for those commands. See Chapter 3 for more information.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The CVSROOT directory in the CVS repository contains several administrative files. Most of these files are editable by the user and are stored in both RCS format (with a ,v suffix) and plain text to be used by CVS. With three exceptions, these files can be checked out, edited, and committed like any other CVS file.

The history and val-tags files should not be edited. The passwd file should never be checked out; it should be edited in place.

If your version of CVS is older than 1.12.6, see Chapter 7 for the scripting file syntax.

Between 1.12.6 and 1.12.10, there were significant changes to the CVSROOT files, and it's obvious that a lot of work is going into improving the features these files make possible.

If you are running a version of CVS later than 1.12.13 (the current version while I'm writing this), it's worth checking the documentation for newer nifty features.

As of CVS 1.12.6, the syntax for scripting files changed. If you're using an older version of CVS, please see Chapter 7 for information on the file syntax. If you have different versions of CVS in the repository and the clients, see Chapter 9 for advice on cross-version issues.

In versions later than 1.12.6, whether you use the new or old format for the scripting files is controlled by the configuration option UseNewInfoFmtStrings. The valid options are yes (to use the new format) and no (to use the format prior to 1.12.6). These options are set in the config file, normally stored in the CVSROOT directory.

The file syntax is as follows:


name-pattern action

The name-pattern is a regular expression that must match a relative path within the repository, or one of the special words DEFAULT and ALL. It is separated from the action by one or more spaces or tabs. Regular expressions are explained later in this chapter.

The action is a command-line template, or the filename (and path) of a script plus any parameters required for that script. It is good practice to use the full pathname of the script, with the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The administrative files in CVSROOT can use several types of variables: internal, environment, and shell variables. You can use these variables to pass parameters to the scripts in the scripting files, or you can use them as part of command-line templates.

The internal variables allow you to use information CVS stores about the currently running command. The environment variables are used to access information from the environment the command is running in, and the shell variables are used to access information about the shell.

Three environment variables are set when CVS runs commands or scripts from CVS administrative files:

CVS_USER: This variable is meaningful only with the pserver access method. It refers to the CVS username provided in the leftmost field of the appropriate line in CVSROOT/passwd. If this username does not exist, the variable expands to an empty string.
LOGNAME and USER: Both of these variables contain the username of the user calling the CVS process.

In the pserver access method, the username is the third field of the line in passwd. If no username is there, the CVS_USER value is used.

The syntax for referencing a CVS internal variable is ${ VARIABLE }. The $ VARIABLE syntax can also be used if the character immediately following the variable is neither alphanumeric nor an underscore (_).

These are the internal CVS variables:

COMMITID

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

In CVS, all dates and times are processed by a version of the GNU getdate function, which can translate dates and times given in several different formats. Case is always irrelevant when interpreting dates. Spaces are permitted in date strings, but in the command-line client, a string with spaces should be surrounded by quotes. If the year is 0 to 99, it is considered to be in the twentieth century.

If a time is not given, midnight at the start of the date is assumed. If a time zone is not specified, the date is interpreted as being in the client's local time zone.

For the canonical information on CVS and dates, see the information on getdate at http://www.gnu.org/software/shishi/manual/html_node/Date-input-formats.html.

The legal time and date formats for CVS are defined by the ISO 8601 standard and RFC 822 as amended by RFC 1123. Other formats can be interpreted, but CVS is designed to handle only these standards.

Section 11.4.1.1: ISO 8601

The basic ISO 8601 date format is as follows:


year-month-day hours:minutes:seconds

All values are numbers with leading zeros to ensure that the correct number of digits are used. Hours are given in 24-hour time. This produces the structure YYYY-MM-DD HH:MM:SS, which is internationally acceptable and can be sorted easily. You can use a date, a time, or both.

If you're using ISO 8601 format with the hyphens, the full date is required in CVS. The YYYYMMDD date format is also acceptable and can be abbreviated to YYYYMM or YYYY.

The HH and HH:MM time formats are acceptable. Times can also be specified without the colon, so HHMMSS or HHMM are usable.

Be aware that HHMM may be misinterpreted as YYYY. Get into the habit of using separators.

In strict ISO 8601 format, a T is required between the date and the time, but CVS understands this format with or without the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Several environment variables affect CVS. Some are used only when CVS is the client, and some are used only when CVS is the server. In local or fork modes, both sets are used.

The environment variables in the following list are read and used by the process that runs on the client computer and must be in the calling user's environment:

COMSPEC: OS/2 only. This variable sets the command interpreter and defaults to CMD.EXE.
CVS_CLIENT_LOG: Used for debugging CVS in client/server mode. If set, everything sent to the server is stored in the CVS_CLIENT_LOG.in file, and everything received by the client is stored in CVS_CLIENT_LOG.out.
CVS_CLIENT_PORT: Used to set the port the client uses to connect to the CVS server in kserver, gserver, and pserver modes. By default, the client uses port 2401 (gserver and pserver) or port 1999 (kserver) to connect to the server.
CVSIGNORE: A whitespace-separated list of filename patterns that should be ignored. See "The cvsignore File," earlier in this chapter.
CVS_IGNORE_REMOTE_ROOT: Obsolete since CVS 1.10. When set, it prevented CVS from overwriting the CVS/Root file if the -d repository_path

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS contains keywords that can be included in nonbinary project files. When CVS finds a keyword in a file that it is checking out, it expands the keyword to provide metadata about the latest revision of the file. You can set keyword-expansion modes on a file to tell CVS whether (and how) to expand the keywords it finds.

Keyword-expansion modes also control line-ending conversion. Unix, Macintosh, and Windows operating systems use different sets of codes to signal the ends of lines. (Linux uses the same codes as Unix.) When you commit a file from an operating system that doesn't use Unix line endings, CVS converts the line endings to Unix style. If you are storing binary files, this conversion can corrupt the file. Use the -kb keyword-expansion mode to tell CVS not to convert line endings.

CVS keywords take the form:


$Keyword$

All keywords except Log expand to the format:


$Keyword: value$

In addition to the keywords shown here, you can configure your own keywords using the LocalKeyword configuration option. These are the keywords and the information they show about the file they are in:

Author: The username of the user who committed the last revision.
CVSHeader: Similar to the Header keyword, this contains the pathname relative to the repository root directory, rather than the full pathname. Otherwise, it has the same information as the Header keyword.

This is new as of version 1.12.2. If it conflicts with existing information in your files, you can exclude it using the KeywordExpand configuration option.
Date

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS uses two different forms of pattern matching, depending on which aspect of CVS is attempting to match the pattern. Most CVS functions use sh-style wildcards, but the scripting files in the CVSROOT directory use regular expressions.

This section is not a comprehensive study of regular expressions or wildcards. For a more complete discussion of regular expressions, I recommend Mastering Regular Expressions, by Jeffrey E.F. Friedl (O'Reilly).

Wildcards are used by most CVS functions, including wrappers and ignore files. The wildcards are evaluated by a version of the fnmatch standard function library distributed with CVS.

The wildcards are sh-style, and the symbols used in CVS include:

?

Matches any single character.

\

Escapes the special symbols, so they can be used as literals.

*

Matches any string, including the empty string.

[ ]

Matches any one of the enclosed characters. Within the brackets, the following symbols are used:

! or ^: If either of these characters is the first character after the open bracket, the brackets match anything that is not included in the brackets.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS provides a variety of ways to access the repository. These methods are briefly described in the following sections, and Chapter 8 explains them in more detail.

On the client side, you specify the access method as part of the repository path. If you don't declare one of the following methods, CVS assumes either the local or ext method:

local: Connect to a repository on the same computer as the sandbox, but do not use client/server mode.
ext: Connect with an externally defined rsh or rsh-like connection method (such as ssh). If you use anything other than rsh, the CVS_RSH environment variable must be set on the client computer.

In CVS 1.11.22 and later, extssh is an alias for ext.
fork: Connect to a repository on the same computer as the sandbox as if it were a remote machine. This method is useful if you are trying to diagnose problems with client/server mode.
gserver: Connect to the repository using the GSS-API and Kerberos 5.
kserver: Connect to the repository using Kerberos 4.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Some people like using the command line during development; others prefer graphical interfaces. Graphical user interfaces (GUIs) also use colors and shapes to make output clearer or make the sandbox easier to work with.

Graphical CVS interfaces are available for Windows, Macintosh, Unix, and Linux systems, and there are also two Java graphical interfaces that run on any operating system with a Java Runtime Environment. These GUIs were written by third-party developers and do not come with CVS.

Third-party developers have also written tools to provide an interface between CVS and several of the common integrated development environments (IDEs). These interfaces are most useful to programmers and are available for Microsoft Visual Studio, MetroWerks CodeWarrior, NetBeans, GNU Emacs, and anything that uses the SCC-API (Common Source Code Control Application Programming Interface). IDEs that support the SCC-API include Macromedia ColdFusion, Sybase PowerBuilder, and Microsoft Visual Studio.

CVS is designed for the Unix and Linux operating systems, and it relies on the features of those operating systems. It can behave in unexpected ways when used from a different operating system. The most obvious problem is that Windows operating systems use a different character for line endings than Unix-based systems do. CVS corrects for that particular problem, but other problems are explained in this appendix.

Section A.1: Multi-Operating-System Clients

Section A.2: Macintosh Clients

Section A.3: Unix and Linux Clients

Section A.4: Windows Clients

Section A.5: Integration Tools

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

If your development team is not familiar with CVS, you may want to ensure that everyone is using the same CVS client. This step helps minimize support problems; if someone has a problem, his fellow developers are familiar with the tools he's using and can offer helpful advice.

The clients described in this section look and operate the same across several different environments. The first three represent a set of clients that are designed for all three major operating systems—Unix/Linux, Macintosh, and Windows—and work from the same base code. The other GUI clients are Java clients that work on any operating system with a Java Runtime Environment, and a client called Concurrent Versions Librarian.

Three GUI clients—gCVS, MacCVS, and WinCVS—represent a set of clients available from the same development team that work identically across Unix/Linux, Macintosh, and Windows operating systems. The clients are detailed and implement most of the functions available from the CVS command line. Using these clients, you can create a new repository, tag files, create watches, and report on the differences between files. These clients are available from http://www.wincvs.org and http://cvsgui.sourceforge.net.

gCVS is for Linux and Unix (including Mac OS X), WinCVS is for Windows, and MacCVS is for Macintosh (both pre-OS X and post-OS X versions exist). Because their interfaces are so similar, these clients are good for groups that develop software across different operating systems.

These clients are laid out with three main windows, as shown in Figure A-1 (gCVS) and Figure A-2 (WinCVS). The leftmost window contains a directory tree, the base directory of which is configurable. The upper-right window shows the contents of the current directory, and the lower-right window shows the output of the CVS commands that you execute using the GUI.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

There are three clients available specifically for the Macintosh operating system: MacCVS (described earlier in "Multi-Operating-System Clients"), MacCVSClient, and MacCVS Pro.

If you are running Mac OS 9 or earlier, be aware of two issues:

The Macintosh CVS clients for OS 9 and earlier don't have built-in SSH support. You can use SSH by following the tunnel workaround in "Installing MacCVS."
CVS clients in Mac OS 9 and earlier may have line-ending issues, as described in "Windows Clients," later in this chapter.

OS X does not have either of these problems, as it has a built-in SSH client and both OS X and CVS use Unix-style line endings.

If you are running Mac OS X, in addition to using the Macintosh-specific clients that are mentioned in this chapter, you can use the CVS command-line client, as well as the Unix and Linux graphical clients.

MacCVSClient is available for OS X and earlier versions from http://www.heilancoo.net/MacCVSClient/.

The main display of MacCVSClient is a modules window, which provides a hierarchical list of files that includes status information. Output from commands such as diff or log is stored and can be retrieved from this window later in the session, as well as immediately after you run a command. If you switch to another application, then return, MacCVSClient attempts to refresh the cached states and modification times of any open folders.

MacCVSClient for Mac OS X supports SSH. MacCVSClient for earlier versions supports the pserver and ext (rsh-only) repository-access methods. You can configure the repository path in the Preferences dialog from the Edit menu, shown in Figure A-7. Conflicts and the results of the diff command are color-coded to improve readability.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS is native to the Unix and Linux operating systems; consequently, there are no line-ending or capitalization issues. The standard, command-line client is intended for use with Unix and Linux, but there is also a wide variety of graphical CVS clients available for Unix and Linux systems.

Cervisia is available from http://cervisia.kde.org. It requires the QT and KDE libraries, but it runs on Gnome and other graphical environments if the QT and KDE libraries are available.

Cervisia provides a configurable list of frequently used CVS repositories, and configurable key bindings for common commands. Cervisia supports the commit, import, and update commands, as well as the tagging and watching sets of commands. One particularly useful setting is the option to run cvs edit automatically, in order to notify other developers when you intend to edit a file.

Cervisia has two main sections in its display screen, shown in Figure A-9. The upper section lists files and directories, and the lower section displays the output of the CVS commands that Cervisia executes for you. Right-click on a file in the upper section to open a menu with options to open the file in an editor, commit a changed file, add a file, remove a file, or run a diff over two revisions of a file.

Figure A-9: The Cervisia CVS client

The Resolve menu option, which you can access by right-clicking the mouse, supports automatic conflict resolution. When you invoke automatic conflict resolution, Cervisia displays both files, as well as the merged version of the two files. Cervisia then allows you to choose from several methods for handling any conflicts that resulted from the merge.

Pharmacy is available from http://pharmacy.sourceforge.net

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

There are two graphical CVS clients available specifically for Windows. One is WinCVS, which is described in "Multi-Operating-System Clients" earlier in this chapter. The other is TortoiseCVS, which modifies the way Windows Explorer presents files.

Following are some issues you might encounter when using CVS from Windows. These issues apply equally to WinCVS and TortoiseCVS.

Line endings differ between Windows and Unix

CVS automatically attempts to convert the line endings of text files to Unix format. This feature is helpful in text files, but it causes problems in binary files that are committed accidentally as text files. When a binary file is corrupted because CVS tried to "fix" the line endings, often you can recover with the following procedure:

Back up the current sandbox copy of the file.
Update the file with cvs update to bring the repository version into the sandbox and reconvert the line endings.
Check the file to ensure that it is no longer corrupt. If it is still corrupt, roll back to the most recent uncorrupted version (hopefully, the backup).
Use cvs admin -kb filename to convert the default keyword-expansion mode of the file to binary.
Recommit the file to the repository with cvs commit -f.

SSH may attempt to convert line endings

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Developers rarely use CVS in isolation. The tools described in this section coordinate CVS with other programs. Some integrate CVS into IDEs; others are used in separate windows but ensure CVS can manage an IDE's files properly.

abCVS is a plugin for CodeWarrior that allows you to use CVS without leaving the CodeWarrior IDE. It requires CodeWarrior and a command-line CVS implementation such as CVSNT (explained in Appendix B). The developers of abCVS also recommend that you have a CVS client such as WinCVS.

abCVS implements the standard suite of necessary CVS commands, along with some of the additional features. Most commands can run on a single file, or they can run recursively down a directory tree. abCVS is available from http://www.iaanus.com/abCVS/.

Anjuta is an IDE for the Linux and Unix operating systems that relies on the Gnome libraries. It supports more than a dozen languages (including C/C++, Java, Python, Perl, and ADA) and provides an integrated debugging facility, syntax highlighting, context-sensitive help, and support for autoconf and automake.

Anjuta provides simple, clean access to CVS commands on files in CVS sandboxes, including an intuitive interface to cvs diff. Anjuta is available from http://anjuta.org.

BBEdit is an HTML and text editor for the Macintosh that includes an integrated CVS and Subversion client that supports multiple repositories. BBEdit is available from http://www.barebones.com/products/bbedit.html.

CVSIn is an add-in for Microsoft Visual Studio that integrates Microsoft Visual Studio and WinCVS. It permits most simple CVS commands to operate directly from Microsoft Visual Studio and relies on WinCVS for more complex CVS commands and commands that operate on directories rather than individual files.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS is an open source program, and all the information necessary to interface to it or change it is freely available. It is also a very popular system. The combination of these two factors means that a wide variety of programs and tools have been written for CVS.

The tools in this appendix range from a port of CVS to the Windows family of operating systems, to a small tool to mail log messages automatically. Other programs include several different viewers to display the contents of the repository with an HTTP server and a useful program that implements access-control lists.

Section B.1: CVS Variants

Section B.2: Distribution Tools

Section B.3: Logging Tools

Section B.4: Metadata Tools

Section B.5: Converters

Section B.6: Miscellaneous

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The CVS license allows you to modify the CVS code and distribute the modified code (read the license for the exact requirements). Several variants, described in the following sections, are provided by developers who have produced expansions of CVS for specific purposes.

CVS/MVS is a port of CVS for the MVS (Multiple Virtual Storage) mainframe operating system, also known as OS/390 and zOS. CVS/MVS requires MVS with POSIX configured, and the HFS (Heirarchical File System).

CVS/MVS is a port of both the server and the command-line client.

CVS/MVS is available at http://dccmn.com/cvsmvs/.

cvs-nserver is a rewrite of the CVS network code, to allow support for SSL (Secure Sockets Layer) tunneling and ACLs (Access Control Lists), among other features. ACLs are available in CVS as an added piece of code (see "cvs_acls " later in this chapter) but are native to cvs-nserver. The authentication is also separated out from the main code in cvs-nserver, to make security audits easier and to include PAM (Pluggable Authentication Modules) availability in the code. cvs-nserver is available at http://cvs-nserver.sourceforge.net/.

CVSNT is an alternative CVS server for Windows (NT, 2000, XP, and 2003), Unix, Linux, OS/400, and Mac OS X. It includes a graphic client as well as the server, and can be used with some of the integration tools described in Appendix A.

As well as running on Windows operating systems, CVSNT provides an additional access method, sspi, that authenticates using Windows domain passwords. The company which makes it provides a free open source version, and also provides packages which contain the free code, additional code and documentation, and commercial support. CVSNT is available at http://www.march-hare.com/cvspro/.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Often, you may want to develop a CVS project and publish the files for display or download. You can publish the resulting files with a build script or a script in one of the CVSROOT files. Alternatively, you can use one of the tools in this section, all of which display CVS project files.

Some of the tools in this section display the repository; others export files from the repository for publication. Some retrieve the difference between the revision they have and the latest revision in the repository, then patch the revision they have and display the final files.

Chora provides the ability to view or download the files in a CVS repository using a web browser. It integrates with the other web tools available at http://www.horde.org. The CVS integration is stored in a single library, so you can customize the rest of the display.

In file mode, every revision of a file is displayed along with log messages, and you also have the ability to display the differences between revisions. Chora has a nifty branch visualization tool, as well. Chora is available from http://www.horde.org/chora/.

CVSup is a tool for distributing files across a network. It can be used with most file types and understands CVS project files. If desired, it can use zlib compression to reduce network load.

If CVSup is working from CVS files, it distributes the differences rather than the files as a whole, saving bandwidth and minimizing the network load. It also understands tags and distributes specific tagged versions if configured to do so.

Note that in CVS 1.12.1 and later, the environment variable $CVS_LOCAL_BRANCH_NUM is available to support local branching. CVSup is available from http://www.cvsup.org.

This tool publishes CVS files using FTP. It was developed for web sites that use CVS for content management, but for which the administrator of the server requires that updates be made using the FTP protocol.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

CVS log messages often contain useful information for project managers, programmers, and other CVS users. There are many tools that manipulate log messages, including tools to create a change log automatically, mail log messages, and change the format of log messages. These tools are most useful if you and your development team enter meaningful log messages.

CHalogen is a change-log generator that relies on the CVS project files being tagged at each significant stage of the project. It generates a change log that displays the changes between tag points. The generated change log is in HTML format.

CHalogen can run as a CGI script or from the command line. It is available from http://www.softwarebee.de/products/chalogen/.

clmerge is a script that merges conflicts in a GNU-style change log. The change log is sent to the standard output, so the script output should usually be redirected to a file. This script is useful as a postprocessor to change log generation programs. clmerge is available from the contrib directory in the CVS source code.

These scripts are designed to work together. commit_prep ensures that the Id keyword is present in the file and checks the version number of the keyword. It prevents older revisions from being copied into the sandbox and replacing an existing revision. It also records information for log_accum.

log_accum consolidates the log messages from a single commit of multiple directories and mails the resulting consolidated log messages—including a consolidated list of which files were added, removed, and modified—to a specified address.

These scripts should be called from the scripting files in the CVSROOT directory. commit_prep and log_accum are available from the contrib directory in the CVS source code.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The tools described in this section provide metadata about the CVS project files or use existing file metadata to provide additional functionality. Using these tools, you can search your log comments or your repository, see a graph showing the rate of file accesses over the past week, or find out who changed which files most recently.

CVS Monitor is a specialized CVS client that displays module and file information, graphic summaries of user activity within modules, change logs, file histories, and other information. It runs as a CGI script and presents its output in a web browser. CVS Monitor is available from http://ali.as/devel/cvsmonitor/.

CVSPlot is a Perl script that plots statistics from a CVS project, such as the number of lines of data or the number of files in a module. It generates the results as a text file or as a .png graph that models the change over time.

CVSPlot is called from the command line and can be used in a script. It allows you to specify the period of time and the file types you are interested in. It requires Perl, and to plot graphically it also requires gnuplot. CVSPlot is available from http://cvsplot.sourceforge.net.

CVSSearch runs keyword searches on the comments stored as a result of file commits, and can do keyword searches in the code as well. Its output includes not only every comment that contains keywords you specify, but also filenames and links to the code that matches the comment.

CVSSearch requires a web server and operates as CGI code. It is available from http://cvssearch.sourceforge.net.

CVSTrac is a combination of repository browser, bug-tracking system, patch-set tracking system, and log manipulator. It can be run as a CGI script, or as a standalone web server, and has several security measures built in, including the ability to have anonymous users with limited permissions. CVSTrac is available from

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

If you want to use CVS with a project that is currently being stored in a version control system other than CVS, you need to convert the files from the other system to CVS. Fortunately, scripts to do just that are available on the Internet and in the CVS source distribution.

The rcs-to-cvs script checks RCS files in to CVS. It also checks in files that didn't previously have source control. It starts by checking whether the current directory's subdirectories exist in the repository; then it commits the files. Files that do not already exist in the repository are checked in as revision 1.1. rcs-to-cvs is available from the contrib directory in the CVS source code.

These scripts convert between RCS and SCCS version control. Note that rcs2sccs supports only one level of branching. Both scripts retain as much of the file metadata as possible. rcs2sccs and sccs2rcs are available from the contrib directory in the CVS source code.

VSSExtractor converts files stored under Visual Source Safe to files in a CVS repository. At the time of writing, it is still under development and hasn't reached its 1.0 milestone yet. VSSExtractor is available from http://sourceforge.net/projects/vssextractor/.

pvcs2rcs reads files from Merant PVCS version control and writes a copy of those files using RCS version control. It acts recursively and leaves the PVCS archive unchanged. pvcs2rcs is available from the contrib directory in the CVS source code.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The tools described in this section are too unique to be categorized easily. However, they are very useful. They range from a tool to clear out old data from the history file, to a tool to mount the repository as a filesystem.

This Perl program sends email when the CVS repository is changed. You can configure when to send the mail, and what to put in the mail message. It's intended to be used in the loginfo or commitinfo scripting files. activitymail is available from http://search.cpan.org/~dwheeler/activitymail/.

This script removes most of the old records from the history file in the CVSROOT directory in the repository. It keeps records of file modification, addition, and removal, keeps the last change to each tag, and removes everything else. This effectively compresses the history file by removing most of the outdated data. cln_hist is available from the contrib directory in the CVS source code.

VCS is an abstracting library for Perl—it allows programmers to write applications which use version control, but which are somewhat independent of the actual version control system in use. One of the version control systems that VCS supports is CVS. The CPAN VCS libraries are available from http://search.cpan.org/~gmccar/VCS-0.14/VCS.pm or from http://sourceforge.net/projects/vcs/.

This script implements access-control lists within CVS. It must be the only script in the commitinfo file in the CVSROOT directory and should be set as DEFAULT so that it is called by all files. The script permits access control based on the username, project directories, and branches within the projects. cvs_acls is available from the contrib directory in the CVS source code.

CVSCheck provides status information for files in the current sandbox. Its output is more concise than the output of

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

Creating this appendix was a good test of this book! You'll find that almost all of the answers refer to sections in the book, and that the ones that don't are still answered in the book, they're just really short answers.

These questions are taken from the info-cvs@nongnu.org mailing list, from the start of 2004 through the time of writing (August 2006), and were all asked at least twice. Some questions from early in that period haven't been answered here, because CVS has since changed.

If you have a question you think I should answer in this FAQ, please send email to bookquestions@oreilly.com.

Section C.1: Usage Questions

Section C.2: Administration Questions

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

These are the everyday questions about the basic use of CVS, collected in one small section for easy reference. These are not "how do I use CVS at all" questions—those are answered in the quickstart guide. Rather, these answers provide useful combinations of commands, or CVS tips and tricks.

The very first step to successfully using a tool such as CVS is putting your files in it. So the questions about that are answered first.

Section C.1.1.1: How do I start a new project?

See "Importing Projects" in Chapter 2 (the quickstart guide) or "Creating a Project" in Chapter 7.

Section C.1.1.2: How do I avoid using a vendor tag and a release tag when I import?

There's no need to do so. When I know I won't be using them, I use a1 and b2 for the tagnames, and ignore them once I've finished using the import command. There's nothing special about a1 and b2, by the way—they're simply legal and meaningless names. You can use fred and ginger, or bert and ernie if you want.

Section C.1.1.3: How do I list all the projects in a repository?

If you have CVS 1.12.8 or later, you can use the easy method to see which directories are in the top level of the repository:


cvs -d repository-path rls .

If there are any modules defined, you can list those with:


cvs -d repository-path checkout -c

There's a discussion of this topic at the end of "Creating a Sandbox," in the "Sandboxes and Repositories" section of Chapter 3.

Section C.1.1.4: How do I check out all the projects in a repository?

You can check out all the projects in the repository with:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Inhaltsvorschau

The repository administrator has a range of problems, from installation and configuration, to security, to ensuring the distribution of committed files. Answers here range from upgrade problems to moving a repository.

The fundamentals of administration include installation, configuration, and upgrades. If you don't get those right, you won't get anywhere.

Section C.2.1.1: How do I install and configure CVS?

There are instructions and examples in Chapters 2 and 6. If you're after a quick and easy installation, use Chapter 2.

Section C.2.1.2: Will upgrading cause me any problems?

In most cases, no. If you are upgrading across the changeover in the scripting files (version 1.12.6), you will start to get deprecation warnings about the change in the scripting files. See the section "Running Scripts" in Chapter 7 for information on getting rid of those warnings.

Section C.2.1.3: How can I automatically create a changelog from CVS?

There are a variety of changelog generators in Appendix B in the section "Logging Tools."

Section C.2.1.4: How do I export a current copy automatically when files are committed?

The section in Chapter 7 titled "The loginfo File," has an example of exporting automatically. The process involves including the export command in the loginfo file, making sure it runs in the background.

Permissions are one thing you must get right, especially if you're protecting important secrets, or are a target for the immature or the criminal. This section answers issues from access control lists to pserver passwords.

Section C.2.2.1: How can I manage CVS file permissions?

See "Securing Your Projects" in Chapter 6.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.