Volume Number: 24
Issue Number: 11
Column Tag: Code

Advanced CVS

Get more out of your CVS Setup

by José R.C. Cruz

In the article "Version Control on a Budget", we learned how to use the CVS tool to manage our project files. Today, we will explore some of the tool's advanced features.

First, we will configure the tool on either the client or server side. Then we will use the tool to keep track of project activity. Finally, we use the tool to manage the project repository.

Be aware that this article assumes that you have a basic understanding of CVS and bash.

You can configure your CVS setup in two ways. One way is to add an invisible file in your home directory. This file, called a run—control file, tells the tool how to handle each SCM transaction. Users can have their own unique run—control files, or they can share a common set of files.

Another way is to change one of the files in the CVSROOT directory. To access those files, type the following statement at the Terminal prompt.

   cvs checkout CVSROOT

CVS then copies the CVSROOT files and stores them on the current work directory. After you made your changes, commit them back to the repository as follows.

   cvs commit —m "Made changes to the CVSROOT files" CVSROOT

First, CVS updates its CVSROOT directory with all your changes. It then applies your changes to all future commands. If you, however, changed a single file, e.g. modules, you can commit just that file as follows.

   cvs commit —m "Made changes to the CVSROOT file 'modules'" modules

Before changing any of the CVSROOT files, make sure to create a backup of those files. This will protect your CVS setup from any errors caused by your changes. One way to backup CVSROOT is to use the tar tool.

Assume, for example, that your CVSROOT directory is stored in /Volumes/Projects/Database. Assume also that you want to store the tarball in /Volumes/Backup. To create the CVSROOT tarball, type the following at the Terminal prompt.

   tar —create —verbose —gzip —file /Volumes/Backups/CVSROOT.tar.gz \
      /Volumes/Database/CVSROOT/*

First, the tar tool copies all the files in the CVSROOT directory. It then stores the copies in the tarball CVSROOT.tar.gz. It also compresses the tarball with the gzip tool.

Now if you made a mistake configuring your CVS setup, type the following statement at the Terminal prompt.

   tar �extract —gzip —file /Volumes/Backups/CVSROOT.tar.gz \
      —directory /

The tar tool then updates your CVSROOT directory with the contents of the tarball CVSROOT.tar.gz.

Use the .cvsignore file to tell CVS which project file to exclude from its repository. CVS checks this file each time it gets an import or an update subcommand. Use your favorite text editor to create this file on your home directory. Make sure to precede the file's name with a period, '.'.

Each line in the .cvsignore file is either a filename or a glob pattern. Glob patterns work in the same way as regex patterns, but they have a simpler syntax.

Listing 1 is a sample of entries in a .cvsignore file. The first entry matches the invisible file .DS_Store. The second matches any file with a .dbug extension. And the third matches any HTML files that have the name foobar or foobur.

   .DS_Store
   *.dbug
   foob[au]r.htm

Before you install your .cvsignore file, be aware that CVS already excludes certain file types by default. A sample of these file types are as follows.

*.a *.bak *.BAK *.exe *.o *.obj *.old *.orig

For a complete list of excluded file types, consult the online CVS manual (see reference).

Finally, you can tell CVS to disable your .cvsignore file for certain tasks. To do so, add the —I ! option to your import or update subcommand (note the '!' character). This option disables not only your .cvsignore file but also the default list of file types that CVS ignores.

Use the .cvsrc file to set the default options for either the CVS tool or any of its subcommands. Like the .cvsignore file, the .cvsrc file also goes into your home directory. Use your favorite text editor to create this file.

Each line in the .cvsrc file has the following syntax.

   cvs | subcommand option [option]

If the leftmost item is a subcommand, the option argument is one of the option flags used only by that subcommand. But if the leftmost item is CVS itself, the option argument is one of the global options available to that tool. Those options apply to all CVS transactions. Read the online CVS manual (see reference) for a list of available options.

Listing 2 is a sample of entries in a .cvsrc file. In the first line, the —r option tells CVS to set the states of the project files as read—only. The —q option tells it to keep its feedback messages to the bare minimum.

In the second line, the —f option tells CVS to allow committals even if none of the project files have changed. In the third line, the —f option tells CVS to always export the head revision. The —P option tells the tool to remove any empty directories from the exported project.

   cvs —r —q
   commit —f
   export —f —P

Any changes you made to the .cvsrc file are used by the next CVS command. You can, however, tell CVS to ignore the .cvsrc file for certain tasks. To do so, use the —f global option.

Assume, for example, you are using the .cvsrc file shown in Listing 2. To commit only those files that you have changed in project foobar, type the following statement.

   cvs �f commit foobar

Do not add the —f global option to the .cvsrc file. This is an unsupported setting and can result in aberrant behavior.

Use the cvswrappers file to tell CVS which project files are text files and which are binary files. Use it also to tell CVS how to store each file type in the repository. There are two versions of this file: one in the CVSROOT directory, the other in the home directory. The name for the home directory version is .cvswrappers.

Each line in the cvswrappers file has the following syntax.

file_name | glob_pattern    option mode [option mode]

The line starts with a filename or a glob pattern. The option argument sets the storage option for that file, the mode argument the storage mode. Each line can have at most two sets of these arguments.

For a binary file, e.g. TIFF, add the following entry to the cvswrappers file.

   *.{tif,tiff} —k 'b'   —m COPY

The above entry matches any file that has a .tif or .tiff extension. It tells CVS not to convert any end—of—line characters in the file. It also tells CVS to always store a copy of that file intact in the repository.

For a non—mergeable text file, e.g. a UTF—16 file, use the same option and modes as the binary file. This is to compensate for CVS's lack of support for Unicode—based files.

For a mergeable text file, e.g. C—headers and sources, add the following entry to the cvswrappers file.

   *.{c,h}    —m MERGE

The above entry matches any file that has a .c or .h extension. If the repository has a copy of that file, CVS stores only the differences between the two. Otherwise, CVS will store an intact copy of the text file.

Now if you have two versions of the cvswrappers file present, CVS will use the entries from both files as one. If both versions of the file have entries for the same filename or glob pattern, CVS will use the entry from the CVSROOT/cvswrappers.

Finally, you can override the entries in both cvswrappers files by adding a —k option to your CVS statement. Read the online CVS manual (see reference) to learn which subcommand uses the —k option.

Use the modules file to set shortcuts to specific projects or items in the repository. Shortcuts reduce the amount of typing needed. They are also easier to remember if chosen correctly.

Each line in the modules file has the following syntax.

shortcut    [options]    repository_path

The options argument defines how the shortcut will work. It has one of two possible values: —a for an alias and —d for a directory. The repository_path argument is the path to the item or project in the repository.

Listing 3 is a sample of shortcuts in a modules file. The first shortcut tells CVS to retrieve the items in project foobar. Also, CVS saves those items under the directory MyFoo.

The second shortcut tells CVS to retrieve only the items in the graphics directory of project foobar. The —a option then tells the tool to save those items under the same directory of foobar/graphics.

The third shortcut tells CVS to retrieve the items in project foobar. But the '!' token tells it to exclude those items in the directory foobar/graphics. Again, the —a option tells the tool to save the retrieved items in the directory foobar.

The fourth shortcut tells CVS to retrieve the project items referred to by the shortcut NoPics. Note the ampersand symbol, '&', in front of the referring shortcut.

The fifth shortcut tells CVS to retrieve the items in project foobar. Also, the —d option tells the tool to store those items under the directory Test/foobar.

Finally, the sixth shortcut tells CVS to retrieve only the file foobar.css. And the —a option tells the tool to save the file in the directory foobar/styles.

   MyFoo             foobar
   MyPics       —a    foobar/graphics
   NoPics       —a    !foobar/graphics    foobar/
   PicFree          &NoPics
   MySite       —d    Test    foobar
   MyStyles    —a    foobar/styles/foobar.css

Tracking project activity is an important part of the work cycle. It helps identify which files got the most attention and those that got the least. It helps measure the number of changes made to each file. Tracking also shows which users worked on which files, and the time spent on each file. It can also help users coordinate their efforts and avoid possible conflicts.

Use the cvs log command to list the changes made to the project or file. For example, to list all the changes to the file foobar.htm, type the command as follows.

   cvs log foobar.htm

CVS then displays the list on the Terminal window. To save the list of changes into a file, e.g. foobar.log, use the '>' operator.

   cvs log foobar.htm > foobar.log

You can restrict the list to a specific date or revision range. To restrict it by date, use the d option. For example, to show only changes made between 2007 Aug 1 and 2007 Sep 1, type the command as follows.

   cvs log —d"2007/08/01<2007/09/01" foobar

Notice that there is no space between the —d option and the date range. Also, notice the use of the '<' token to specify an exclusive range. For an inclusive date range, retype the command with a '<=' token.

   cvs log —d"2007/08/01<=2007/09/01" foobar

To restrict the range by revision number, use the —r option. For example, to show only the changes made between revisions 1.2 and 1.5, type the command as follows.

   cvs log —r1.2:1.5 foobar

Notice again that there is no space between the option and the range. Notice also the use of the ':' token to specify an inclusive range.

To learn other useful log options, read the online CVS manual (see reference).

Figure 1 is a sample output from the cvs log command. The header section tells us where the project file is located on the repository. It tells us what tags belong to the file (gold), and the revision count (red). It also shows a short description of the file (green), if one is available.

Right after the header is a list of changes made to the file. Each entry starts with the revision number and date of the change (green). It shows the user who made the change (blue), the file's current state (red), and the number of lines that changed (pink).

Figure 1. Sample output of the cvs log command

The output of the cvs log command, however, is not customizable. Creating it is a separate step, making it prone to neglect. It can also be changed either by accident or by intent.

But you can have CVS create the log output automatically. You can customize the output to suite your needs. You can also make the output a part of your project file, thus serving as a version history for that file. You can do all these by using revision keywords.

Table 1 is a list of common revision keywords. To use these keywords, add them within a comments block. Doing so will tell the file's owner to ignore the keywords. Also, when you commit the file to the repository, CVS updates each keyword with the right information.

Keyword Description

$Author$ Name of the last user who made the change

$Date$ Date when the change was made

$Header$ Basic header information

$Log$ A description of changes made to the file

$State$ State of the file when the change was made

$Source$ Location of the project file in the repository

$Revision$ Revision number assigned to the file

Listing 5 is a sample revision block for an HTML file. Notice the block is placed between the comment marks <!— —>. Assume you added this block to the file foobar.htm. Then you committed the file by typing the following command.

   cvs commit —m "Added the revision history block" foobar.htm

   <!— 
      $Source$
      $Author$
      $Date$
      Revision history:
         $Log$
   —>

CVS responds by first updating the revision block as shown by Listing 6. It then commits the updated file to the repository. Notice that the block retains the keywords, even after the update. Also, future committals will cause CVS to insert more entries right after the $Log$ keyword.

   <!— 
      $Source: /Volumes/Projects/CVS/foobar/foobar.htm,v $
      $Author: s_hardin $
      $Date: 2007/09/11 04:30:50 $
      Revision history:
         $Log: foobar.htm,v $
         Revision 1.2  2007/09/11 04:30:50  s_hardin
         Added the revision history block.
   —>

Use the cvs watch command to keep track of users working on the same project. This command performs two functions. First, it sets the project file to a read—only state during a checkout or an update. Second, it adds a user to the watch list.

The basic syntax of the cvs watch command is as follows.

   cvs watch operator [file ...]

The operator argument sets the behavior of the command. It has four possible values: on, off, add, and remove. You can also list more than one file after the command.

Let us assume that you are working on project foobar with another user named h_mallow. To add the file to the watch list, use the cvs watch command with an on operator.

   cvs watch on foobar.htm

When h_mallow checks out a copy of the file, he will find the file in a read—only state. To remove the file from the watch list, use the command with an off operator.

   cvs watch off foobar.htm

Since you placed the file on the watch list, you should inform h_mallow that you are watching that file. To do so, use the cvs watch command with an add operator.

   cvs watch add foobar.htm

To remove yourself from the list, use the command with a remove operator.

   cvs watch remove foobar.htm

To get a list of other users watching the file, use the cvs watchers command.

   cvs watchers foobar.htm

Listing 7 shows a sample output of the above command.

   foobar.css      h_mallow edit    unedit  commit
   foobar.htm      youRhere edit    unedit  commit

Now assume that user h_mallow added the file foobar.css to the watch list. When you checked out that file, you will find it set to a read—only state. If you want to change the file, first use the cvs edit command to change its state to read/write.

   cvs edit foobar.css

When user h_mallow types the cvs watchers command, he gets the following list of users.

   foobar.css      h_mallow edit    unedit  commit
      youRhere tedit   tunedit tcommit
   foobar.htm      youRhere edit    unedit  commit

He then sees that you have started work on the foobar.css file.

Once you have made your changes to foobar.css, use the cvs unedit command to set the file's state back to read—only.

   cvs unedit foobar.css

Committing your changes to the repository will also do the same thing. And both actions will remove you from the watch list.

Sometimes, you want to make minor changes to your project repository. You may want to set tags to specific project revisions. Or you may want to generate a patch for a specific project file.

CVS gives you the means to make these changes directly on the repository. But be aware that you could easily mess up the repository as well. Make sure to create a backup of your repository beforehand. Also, make sure to allow only a small group of trusted users to change the repository itself.

Now, you use the cvs tag command to assign a tag to a file or project from your working copy. To do the same directly on the repository, use the cvs rtag command. Unlike the former, you do not need a working copy of the project to use this command.

The basic syntax of the cvs rtag command is as follows.

   cvs rtag [options] tag file | directory | project

This command shares many of the same options as the cvs tag command. For example, that you are managing the project foobar. To set the tag alpha1 to the latest revision of the file foobar.htm, type the command as follows.

   cvs rtag alpha1 foobar.htm

To set the same tag to the latest revision of project foobar, type it as follows.

   cvs rtag alpha1 foobar

Suppose a user gave the wrong tag beta1 to the latest revision of foobar.htm. To remove that tag, use the —d option.

   cvs rtag —d beta1 foobar.htm

But make sure that the tag exists before you remove it. Otherwise, CVS will return an error message. Use the cvs status command with a —v option to get a list of tags.

   cvs status —v foobar.htm

CVS then displays a list of all tags assigned to the file foobar.htm (Figure 2, gold).

Figure 2. Sample output of the cvs status —v command.

Assume you want to set the tag dev1 to revision 1.15 of foobar.htm. To do so, use the cvs rtag command with a —r option.

   cvs rtag —r 1.15 dev1 foobar.htm

If you want to set the same tag to the file foobar.css revised on 2007 Sept 01, use the —D option.

   cvs rtag —D 2007/09/01 dev1 foobar.css

Again, make sure that either revision number or date exists on the repository. If you are not sure, add a f option to the command.

   cvs rtag —f —r 1.15 dev1 foobar.htm

If CVS fails to find the specified revision or date, it will set the tag to the latest revision of that file.

Suppose a user sets the tag GM1 to the wrong revision of foobar.htm. To move that tag to the correct revision, e.g. 2.0, use the —F option.

   cvs rtag —F —r 2.0 GM1 foobar.htm

First, CVS removes the tag GM1 from foobar.htm. Then it assigns the same tag to revision 2.0 of that file.

Assume that project foobar has a subdirectory named scripts. To set the tag alpha3 to all the files in that subdirectory, type the cvs rtag command as follows.

   cvs rtag alpha3 foobar/scripts

Not only will CVS tag all the files in scripts, it will also locate any scripts subdirectories and tag their files as well. To tag only those files in the scripts subdirectory, use the —l option.

   cvs rtag —l alpha3 foobar/scripts

Now, you use the cvs diff command to compare two revisions of a file or project. But to do the comparisons directly on the repository, use the cvs rdiff command. Again, unlike the former, you do not need a working copy of the project to use this command.

The basic syntax of the cvs rdiff command is as follows.

   cvs rdiff [options] file | project

This command shares many of the same options as the cvs rdiff command. Assume, for example, that you are managing the project foobar. To set the tag alpha1 to the latest revision of foobar.htm, type the command as follows.

Assume you are working on project foobar. To compare its latest revision against revision 1.5, type the cvs rdiff command with a —r option.

   cvs rdiff —r 1.5 foobar

To compare revision 1.1 against 1.5, use two —r options as follows.

   cvs rdiff —r 1.1 —r 1.5 foobar

Make sure the repository contains both revisions, or CVS will return an error message. If you are not sure, you can add a —f option to the command.

   cvs rdiff —f —r 1.1 —r 1.5 foobar

CVS will use the latest revision if it fails to find one of the revision numbers.

Suppose you want to check on the project file foobar.htm. To compare its latest revision against the one on 2007 Sep 01, type the cvs rdiff command with a —D option.

   cvs rdiff —D 2007/09/01 foobar/

To compare the file from 2007 Sep 15 against the one on 2007 Sep 01, use two —D options as follows.

   cvs rdiff —D 2007/09/01 —D 2007/09/30 foobar/foobar.htm

Make sure to place the earliest date first. Make sure also that the repository contains both dates. Use the f option if you are not sure.

Now the cvs rdiff command generates its output in one of two formats. The first format, context diff, is the default format. It is the one used by most BSD projects. The second format, unified diff, is a more compact format. It is also the one used by most GNU projects.

Assume you are comparing the latest revision of foobar.css against revision 1.5. To save the results in context diff, type the cvs rdiff command as follows.

   cvs rdiff —r 1.5 foobar/foobar.css > foobar.diff

CVS then saves the comparison results into the file foobar.diff. To save the results in unified diff, add a —u option.

cvs rdiff —r 1.5 —u foobar/foobar.css > foobar.diff

Once you saved the results, you can send the file to non—CVS users. Those users can then update their copy of foobar.css using your diff file and the patch tool. For more information about that tool, type man patch at the Terminal prompt.

Use the cvs admin command to make changes to a project file in your repository. Unlike the previous two commands, you will need a working copy of the project in order to use this command. Also, most changes you make with this command are undoable. Make a backup of the repository to protect yourself from any mistakes.

The basic syntax of the cvs admin command is as follows.

   cvs admin [options] [file]

The file argument specifies which file to change. If this argument is missing, the command will apply the change to all the latest revisions of the project's files. The options argument specifies what changes to make to the file in the repository.

Suppose a user used the wrong message when he committed his changes to the file foobar.htm. To correct the message, first find out the revision number of that committed file, e.g. 1.5. Then use the cvs admin command with a —m option as follows.

   cvs admin —m1.5:"the correct committal message here" foobar.htm

Suppose you want to trim down your project repository. A good way to do so is to use the cvs admin command with a —o option. Then specify a range of revisions to remove from the repository. For example, to remove all revisions of foobar.htm between 1.2 and 1.5, type the command as follows.

   cvs admin —o1.2::1.5 foobar.htm

Note the use of double—colons, '::', when setting the range. To remove revisions 1.2 and 1.5 as well, use a single colon, ':', to set the range.

   cvs admin —o1.2:1.5 foobar.htm

To remove revisions 1.2 and older of foobar.htm, specify the range as follows.

   cvs admin —o:1.2 foobar.htm

To remove revisions 1.2 and newer of that file, specify the range as follows.

   cvs admin —o1.2: foobar.htm

Again, if you want to exclude revision 1.2 from the range, use double—colons, '::', to set the range.

By default, CVS sets all project files to an Exp (experimental) state. Other possible states include Stab, for stable; and Rel, for release. You can also specify your own state label.

Suppose you want to change the latest revision of the foobar.htm file to a Stab state. To do so, use the cvs admin command with a —s option.

   cvs admin —sStab: foobar.htm

To set revision 1.5 of foobar.htm to a Test state, type the command as follows.

   cvs admin —sTest:1.5 foobar.htm

Notice that there are no spaces between the —s option and the state label itself. Notice also that the revision number comes after the ':' token. To find out if CVS set the correct state, type cvs log foobar.htm. CVS will display the file's state in one of its log entries (Figure 1, red).

CVS also leaves the project file's description blank. To add your own description, use the cvs admin command with a —t option. For example, to add a description to foobar.htm, type the command as follows.

   cvs admin —t—"This is a test HTML file." foobar.htm

Note the use of a dash, '—', to separate the —t option and the description string. To add a much larger description, first add the description to a separate file, e.g. foobar.txt. Then type the cvs admin command as follows.

   cvs admin �tfoobar.txt foobar.htm

Also, when you type cvs log foobar.htm, you will see the description string on that command's output (Figure 1, green).

This article has shown you a handful of ways to get more out of your CVS setup. It showed how to configure your setup to suit your needs. It showed how to track changes to project files and the users that made them. It also showed how to maintain the repository, its tags and diffs.

Despite its limits, CVS is still a popular tool for managing OS X projects. It is available on all versions of OS X, and it integrates well with other tools such as BBEdit and Xcode. It also inspired users to create tools that address its limits and extend its capabilities.

It is possible that other SCM tools such as Subversion and Git will finally replace CVS in the near future. Until that happens, however, CVS is a strong management system, alive and well.

Cruz, José R.C. "Version Control on a Budget". MacTech Magazine. Volume 22. Issue 10. (c) 2006 MacTech.

Cederqvist, Per. "Reference manual for Administrative files". CVS—Concurrent Versions System v1.11.22. (c) 2003, 2006 Ximbiot, LLC. Online: http://ximbiot.com/cvs/manual/cvs1.11.22/cvs_18.html#SEC158

Fogel, Karl, Moshe Bar. "Using Keyword Expansion". Open Source Development with CVS, 3rd Edition. (c) 1999, 2000 Karl Fogel. Online: http://cvsbook.redbean.com/cvsbook.html#Using%20Keyword%20—Expansion

Free Software Foundation. "Pattern Matching". Bash Reference Manual. (c) 1991—2002 Free Software Foundation. Online:

http://www.gnu.org/software/bash/manual/bashref.html#SEC35

JC is a freelance engineering writer from North Vancouver, British Columbia. He spends his time writing technical articles; tinkering with Cocoa, REALbasic, and Python; and visiting his foster nephew. He can be reached at anarakisware@gmail.com.