12.5 Configuring Keyword Expansion

In a repository that includes third-party software on vendor branches, it is sometimes helpful to configure CVS to use a local keyword instead of the standard $Id$ or $Header$ keywords. Examples from real projects include $Xorg$, $XFree86$, $FreeBSD$, $NetBSD$, $OpenBSD$, and even $dotat$. The advantage of this is that you can include your local version information in a file using this local keyword (sometimes called a "custom tag" or a "local tag") without disrupting the upstream version information (which may be a different local keyword or a standard keyword). In these cases, it is typically desirable to disable the expansion of all keywords except the configured local keyword.

The KeywordExpand option in the `CVSROOT/config' file is intended to allow for the either the explicit exclusion of a keyword or list of keywords, or for the explicit inclusion of a keyword or a list of keywords. This list may include the LocalKeyword that has been configured.

The KeywordExpand option is followed by = and the next character may either be i to start an inclusion list or e to start an exclusion list. If the following lines were added to the `CVSROOT/config' file:

        # Add a "MyBSD" keyword and restrict keyword
        # expansion
        LocalKeyword=MyBSD=CVSHeader
        KeywordExpand=iMyBSD

then only the $MyBSD$ keyword would be expanded. A list may be used. The this example:

        # Add a "MyBSD" keyword and restrict keyword
        # expansion to the MyBSD, Name and Date keywords.
        LocalKeyword=MyBSD=CVSHeader
        KeywordExpand=iMyBSD,Name,Date

would allow $MyBSD$, $Name$, and $Date$ to be expanded.

It is also possible to configure an exclusion list using the following:

        # Do not expand the non-RCS keyword CVSHeader
        KeywordExpand=eCVSHeader

This allows CVS to ignore the recently introduced $CVSHeader$ keyword and retain all of the others. The exclusion entry could also contain the standard RCS keyword list, but this could be confusing to users that expect RCS keywords to be expanded, so care should be taken to properly set user expectations for a repository that is configured in that manner.

If there is a desire to not have any RCS keywords expanded and not use the -ko flags everywhere, an administrator may disable all keyword expansion using the `CVSROOT/config' line:

	# Do not expand any RCS keywords
	KeywordExpand=i

this could be confusing to users that expect RCS keywords like $Id$ to be expanded properly, so care should be taken to properly set user expectations for a repository so configured.

It should be noted that a patch to provide both the KeywordExpand and LocalKeyword features has been around a long time. However, that patch implemented these features using tag= and tagexpand= keywords and those keywords are NOT recognized.

This document was generated on September, 14 2007 using texi2html 1.76.