Previous section   Next section

11.6 Keywords and Keyword Modes

CVS contains keywords that can be included in nonbinary project files. When CVS finds a keyword in a file it is checking out, it expands the keyword to provide metadata about the latest revision of the file. You can set keyword-expansion modes on a file to tell CVS whether (and how) to expand the keywords it finds.

Keyword-expansion modes also control line-ending conversion. Unix, Macintosh, and Windows operating systems use different sets of codes to signal the ends of lines. (Linux uses the same codes as Unix.) When you commit a file from an operating system that doesn't use Unix line endings, CVS converts the line endings to Unix style. If you are storing binary files, this conversion can corrupt the file. Use the -kb keyword-expansion mode to tell CVS not to convert line endings.

CVS keywords take the form:

$Keyword$

All keywords except Log expand to the format:

$Keyword: value$

These are the keywords and the information they show about the file they are in:

Author

The username of the user who committed the last revision.

Date

The date on which the last revision was committed, in UTC.

Header

A header containing information about the file, including the author, date and revision number, path and filename of the RCS file (project file in the repository), file status, and whether the file is locked. See Chapter 5 for information about file locking.

Id

A header like the one given by the Header keyword, without the path of the RCS file.

Name

The tag name the file was checked out with. This keyword can display a branch or provide a more meaningful identification of a revision than the revision number alone. See Chapter 4 for more information about tags and branches.

Locker

The username of the user who locked the file with cvs admin -l (empty if the file is not locked).

Log

The commit messages, dates, and authors for the file. This keyword instructs CVS to store this information in the file itself. Any characters that prefix the keyword are also used to prefix log lines; this enables comment markers to be included automatically. Unlike most keywords, existing log expansions are not overwritten with the new ones; the new log expansions are merely prepended to the list.

The cvs log command displays all the information that the Log keyword provides.

The Log keyword is best used at the end of a file, to avoid users having to go through all the log messages to get to the important parts of the file.

The log created by the Log keyword does not merge neatly when CVS merges a branch back to the trunk. If your file is likely to be branched and remerged, it is better to use the cvs log command than to store a log within the file.

RCSfile

The name of the RCS file (the project file in the repository).

Revision

The CVS internal revision number of the file. This number is specific to the individual file and does not identify a stage within the project.

Source

The name and path of the RCS file (the project file in the repository).

State

The current state assigned to the current revision, set with cvs admin -s. See Chapter 7.

The keyword-expansion modes in the following list are used in commands and CVS wrappers to control keyword expansion and line-ending conversion. The syntax differs slightly for each use. In commands, you use the mode without a space between the option and the mode (e.g., -kb). In wrappers, you need a space and may need to quote (e.g., -k 'b').

b

Inhibit keyword expansion and line-ending conversion. Use this keyword-expansion mode to signal that a file is binary.

CVS can convert line endings from the form appropriate to the server to the form appropriate to the client. This causes obvious problems when working with binary files.

k

Generate only a keyword name, not a name and value. Use this option when merging different (nonbinary) versions of a file, to prevent keyword substitution from creating spurious merge errors. This option can corrupt binary files.

o

Generate the version of a keyword string that was present just before the current file was last committed, rather than generating a version with the modifications of the last commit. This option is similar to -kb, but with line-ending conversion.

v

Generate only the value of a keyword, rather than the name and value. This is most useful with cvs export, but do not use it for binary files. Once any keyword is removed from a file, further expansions are not possible unless the word is replaced.

kv

Generate the name and value of a keyword. This is the default mode.

kvl

Generate the name and value of a keyword and add the name of the locking user if the revision is locked with cvs admin -l.


  Previous section   Next section
Top