3.6. Removing Files from the Repository
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:
Example 3-15 shows a file being removed. Notice that the file is first removed from the sandbox using the Unix rm command. Only then can you use cvs remove (unless you specify the -f option). Figure 3-11 shows removing a file in Cervisia.
Example 3-15. Using cvs remove
Figure 3-11. Using cvs remove in Cervisia
cvs remove is affected by tags, and CVS cannot remove a file that has a sticky tag or a sticky date. Chapter 4 explains sticky tags and dates in detail. Here we will discuss only how they affect file removal.
When a file is retrieved using a tag name or a date, the file in the sandbox reflects the state of the repository at the time the tag or date occurred. Such files are not intended to be changed: they're only static representations of the past. That they are static implies that such files can't be removed, either.
When you try to remove a nonremovable sticky-tagged file, CVS issues an error message such as the following: cvs server: cannot remove file 'filename' which has a numeric sticky tag of '1.3'. Correct this error by using cvs update -A, then remove the file.
3.6.1. Retrieving Removed Files
Retrieving a removed file is similar to retrieving a previous revision of a file. If you need to look at a file without making changes, use either:
cvs update -r revision
cvs checkout -r revision
If you need to make changes, you can use any of three methods to bring the removed file back into active service. The methods are explained in the following sections. Methods 1 and 2 are essentially the same, differing mostly in whether the file is added before or after the data is retrieved. Method 3 uses file merging to accomplish the task and should not be used on binary files. The three methods achieve the same result, so you can choose the one that you will remember most easily.
18.104.22.168. Method 1
Method 1 creates an empty file of the same name, uses cvs add to declare the file active, and then uses cvs update -j to replace the empty file with the file as it was just prior to the removal. The steps are as follows:
Example 3-16 illustrates this method by retrieving main.c, which was previously removed using cvs remove.
Example 3-16. Retrieving a removed file, method 1
22.214.171.124. Method 2
Method 2 uses cvs update to retrieve the file to stdout, sends stdout to a file of the same name as the removed file, and then uses cvs add to restore the file to the repository. The steps are as follows:
Example 3-17 shows this method of retrieving a removed file.
Example 3-17. Retrieving a removed file, method 2
126.96.36.199. Method 3
Method 3 merges the removed file with the unremoved file just before its removal. The steps are as follows:
Example 3-18 shows this method of retrieving a removed file.
Example 3-18. Retrieving a removed file, method 3
3.6.2. Removing Directories
CVS doesn't include any mechanism for removing directories from a repository. Any directory that contained files at a point in a project's history should be retained so that earlier revisions of the project can be retrieved.
If a directory is deprecated and its contents are no longer needed for the project, use cvs remove to empty the directory and its subdirectories of files other than the contents of the CVS subdirectory. To prevent these empty directories from being added to the sandbox, use the -P flag to the cvs update and cvs checkout commands. The -P flag instructs CVS not to download empty directories to the sandbox.
To remove a directory that has never contained any files, or to remove any directory completely, edit the repository, as described in Chapter 6.