Essential CVS | O'Reilly Media

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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."

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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).

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|

Table of Contents