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.

M filename

Modified in your working directory. The file in the sandbox is more recent than the repository version, or the sandbox and the repository both had changes that the system could safely merge into your sandbox copy (need to run a cvs commit).

P filename

Patched in the sandbox; similar to U (updated successfully), but in this case CVS sent only the changes, not the entire file.

R filename

Marked for removal but not yet removed from the repository (need to run a cvs commit).

U filename

Updated successfully. A newer version in the repository has replaced your sandbox version.

? filename

The file is in your working directory but not in the repository. CVS doesn’t know what to do with it. It’s common to see this marker next to temporary or intermediate files that you haven’t cleaned up.

The A, R, and M codes mean that your sandbox contains changes that are not in the repository and it would be a good idea to run a cvs commit.

Figure 2-8 shows the update dialog from gCVS. In the background, at the bottom right, you can see the dialog from a successful update, showing that file1 is modified in the sandbox.

Figure 2-8.  File update with gCVS

If CVS can’t merge a modified file successfully with the copy in the repository, it announces the conflict in the output of cvs update, as shown in Example 2-17. Figure 2-9 shows a conflict in gCVS.

Example 2-17. File conflict

cvs/example$ cvs update
cvs server: Updating .
RCS file: /var/lib/cvsroot/example/file1,v retrieving revision 1.3
retrieving revision 1.4

Merging differences between 1.3 and 1.4 into file1
rcsmerge: warning: conflicts during merge cvs server: conflicts found in file1
C file1

Figure 2-9.  File conflict with gCVS

CVS automatically merges files when the changes are on different lines. If a line in the repository copy is different from the corresponding line in the sandbox copy, CVS reports a conflict and creates a file with the two revisions of the line surrounded by special marks, as shown in Example 2-18.

Example 2-18. Conflict marks

<<<<<<<file 2
This line came from the sandbox.
= = = = = = =
This line came from the repository.
>>>>>>> 1.4

The contents of the original file are stored in .#file.revision in the file’s working directory, and the results of the merge are stored as the original filename.

To resolve the conflict, search the file with the original filename for the pattern of repeated greater-than or less-than symbols. Study the two options for each set of changes, and discuss the changes with the person who committed the previous ver sion of the file. (Use cvs log filename  to find out who committed the previous version; see Chapter 5 for information on cvs log.)

Once you and the previous author have agreed on how the file needs to be changed, edit the file accordingly and remove the conflict markers. Then commit the changed file.

How I Lost Penny’s Changes

The first time I used CVS, I had no idea what I was doing. My coworker sent me to man cvs, which is just a summary of the commands, with no tutorial information. Penny, who I was working with, had never used it either.

We struggled through, until we reached our first conflict. We couldn’t understand why Penny couldn’t commit, and after some time, decided to remove Penny’s existing file and update from the repository. I’m sure we thought CVS must have saved it somehow.

If only we’d updated with Penny’s file still in her sandbox. But we didn’t, and the work she had done was lost.

Penny, if you ever read this, I’m sorry. And now I know what I should have done.