23.8.9.3 Inserting Version Control Headers

Sometimes it is convenient to put version identification strings directly into working files. Certain special strings called version headers are replaced in each successive version by the number of that version, the name of the user who created it, and other relevant information. All of the back ends that VC supports have such a mechanism, except GNU Arch.

VC does not normally use the information contained in these headers. The exception is RCS—with RCS, version headers are sometimes more reliable than the master file to determine which version of the file you are editing. Note that in a multi-branch environment, version headers are necessary to make VC behave correctly (see section Multi-User Branching).

Searching for RCS version headers is controlled by the variable vc-consult-headers. If it is non-nil (the default), Emacs searches for headers to determine the version number you are editing. Setting it to nil disables this feature.

Note that although CVS uses the same kind of version headers as RCS does, VC never searches for these headers if you are using CVS, regardless of the above setting.

You can use the C-x v h command (vc-insert-headers) to insert a suitable header string.

C-x v h

Insert headers in a file for use with your version-control system.

The default header string is ‘$Id$’ for RCS and ‘%W%’ for SCCS. You can specify other headers to insert by setting the variables vc-backend-header where backend is rcs or sccs.

Instead of a single string, you can specify a list of strings; then each string in the list is inserted as a separate header on a line of its own.

It may be necessary to use apparently-superfluous backslashes when writing the strings that you put in this variable. For instance, you might write "$Id\$" rather than "$Id$". The extra backslash prevents the string constant from being interpreted as a header, if the Emacs Lisp file containing it is maintained with version control.

Each header is inserted surrounded by tabs, inside comment delimiters, on a new line at point. Normally the ordinary comment start and comment end strings of the current mode are used, but for certain modes, there are special comment delimiters for this purpose; the variable vc-comment-alist specifies them. Each element of this list has the form (mode starter ender).

The variable vc-static-header-alist specifies further strings to add based on the name of the buffer. Its value should be a list of elements of the form (regexp . format). Whenever regexp matches the buffer name, format is inserted as part of the header. A header line is inserted for each element that matches the buffer name, and for each string specified by vc-backend-header. The header line is made by processing the string from vc-backend-header with the format taken from the element. The default value for vc-static-header-alist is as follows:

(("\\.c$" .
  "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
#endif /* lint */\n"))

It specifies insertion of text of this form:

#ifndef lint
static char vcid[] = "string";
#endif /* lint */

Note that the text above starts with a blank line.

If you use more than one version header in a file, put them close together in the file. The mechanism in revert-buffer that preserves markers may not handle markers positioned between two version headers.