3.10. Binary Files and Wrappers
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.
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
The flag to cvs add works well on a file-by-file basis, but when you need to add or import a large set of files, setting each binary file's expansion mode manually is annoying. CVS wrappers allow you to control the merge methodology or keyword-substitution modes used on a file, based on the filename (usually specified by the file extension). When a file matches a wrapper, the merge method or substitution mode in the wrapper is used instead of the method otherwise used in the command.
Wrappers can be specified using the -W command option for update and import, in the .cvswrappers file in the user's home directory on the client machine, or in the cvswrappers file in the repository's CVSROOT subdirectory.
To specify a wrapper in a .cvswrappers or cvswrappers file, use the following syntax:
wildcard option 'value' [option 'value'...]
Specify a wrapper using the -W command option as follows:
-W "wildcard option 'value'"
In the files, use one wrapper per line.
These are the available wrapper options:
Replace wildcard in the wrapper syntax with a regular expression for pattern matching. Chapter 11 provides a full explanation of CVS pattern matching. These are the most important of the special symbols:
Example 3-24 shows cvs update using a wrapper parameter that specifies the v mode for all files beginning with "Ma". (Note that I use the shell escape character for the bash shell to escape the asterisk.)
Example 3-24. Using cvs update with wrappers