7.2. Distributing Files
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.
7.2.1. checkout and update
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.
7.2.2. Exporting 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: value$ shows in each exported file as value. This can be an advantage when you are publishing a completed release of your project. For example, the string $Revision$ displays as 5.7 and the string $Author$ displays as jenn. Keywords are commonly used in "About this program" displays.
The syntax for cvs export is:
cvs [cvs-options] export [command-options] project_name
cvs export uses a subset of the options available with cvs checkout. It accepts the -D date, -r revision, and -r tag options to specify the revision to be exported. You can also use the -f option, which instructs CVS to use the HEAD revision if the specified revision is not available.
The -l and -R options specify local or recursive operation, and the -k mode option is used to set the keyword-expansion mode. Use the -n option to prevent CVS from running an export program specified in the modules scripting file.
The -d directory option provides a directory name for CVS to export the files to. Otherwise, CVS exports the files and subdirectories to a directory named for the module, or for the project root directory.
If you use -d and are exporting only one file from a subdirectory, CVS removes intermediate directories. For example, cvs export -d shortpath /long/path/to/file will produce a directory shortpath containing file. Use -N with -d to prevent CVS from removing intermediate directories.
Example 7-4 shows an export of the wizzard project.
Example 7-4. Using cvs export
If you are using CVS to manage a web server, FTP site, or other publication system, you may want to ensure that the latest revisions of the project files are in your publication directory. You can do this by automatically exporting the files on a regular basis using cvs export, cvs checkout, or cvs update.
cvs export attempts to write the full revision of each file, and it will not export a file if an existing file of the same name is in the directory it is trying to write to. If you want to overwrite an existing copy of the project or if you want to transmit only changes, cvs checkout or cvs update may be more useful. See the "checkout and update" section earlier in this chapter for more details.
Example 7-5 shows a simple script that exports a project, tests whether the export worked, and then runs an installation script using the make utility. The script in the example could be called from cron or any other Unix or Linux scheduler.
Example 7-5. Export cron script
You can also run a script similar to the one in Example 7-5 to export your project whenever a file has been changed, using the loginfo administrative file or the -i option in the modules file. These files are explained in the following section.