CVS recognizes keywords that can be included in any source file other than a binary file. 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. CVS keywords take the following form:
Example 3-21 shows a file that includes CVS keywords.
# Makefile for the Wizzard project # First created by J Vesperman, 1 September 2002 # # Current revision $Revision: 1.5 $ # On branch $Name: $ # Latest change by $Author: madd $ on $Date: 2003/07/11 20:00:23 $ # Initial declarations CC=gcc SUBDIRS = man doc src lib # Declaring phony targets .PHONY: all clean install all: wizzard echo "all: make complete" clean: rm -f src/*.o rm -f wizzard echo "clean: make complete" . . . # Log record for Makefile changes: # $Log: ch03.xml,v $ # Revision 1.5 2003/07/11 20:00:23 madd # madd final SC edits # # Revision 1.4 2003/07/09 21:31:56 madd # madd SC edits # # Revision 1.3 2003/07/07 21:52:50 madd # madd SC edits # # Revision 1.2 2003/06/27 21:47:43 madd # madd R2 conversion edits # # Revision 1.1 2003/06/26 22:22:10 madd # Initial revision #
Example 3-21 shows a makefile. The keywords are expanded when the file is checked out or updated. Example 3-22 shows the resulting expansions.
# Current revision $Revision: 1.5 $ # On branch $Name: $ # Latest change by $Author: madd $ on $Date: 2003/07/11 20:00:23 $ # Initial declarations CC=gcc SUBDIRS = man doc src lib . . . # Log record for Makefile changes: # $Log: ch03.xml,v $ # Revision 1.5 2003/07/11 20:00:23 madd # madd final SC edits # # Revision 1.4 2003/07/09 21:31:56 madd # madd SC edits # # Revision 1.3 2003/07/07 21:52:50 madd # madd SC edits # # Revision 1.2 2003/06/27 21:47:43 madd # madd R2 conversion edits # # Revision 1.1 2003/06/26 22:22:10 madd # Initial revision # # Revision 1.2 2002/09/01 06:57:23 jenn # Initial code in the Makefile.
The full list of possible keywords is provided in Chapter 11. These are the most commonly used keywords:
The username of the user who committed the last revision.
The date on which the last revision was committed, in UTC.
A header that contains information about the file, including the author, date and revision number, pathname of the RCS file, file status, and whether the file is locked. See Chapter 5 for information about file locking.
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.
Commit messages, dates, and authors, recorded 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 ones are merely prepended to the list.
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 it is likely that your file will be branched and remerged, it is better to use the cvs log command than to store a log within the file.
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.
Do not edit keyword expansions. CVS will change them automatically each time a file is checked out. Altering the format or syntax of an expansion may make it unrecognizable to CVS.
Resist the urge to edit the data stored in the Log expansion. Doing so means that it will differ from the output of the cvs log command, which will create doubt about who actually did what, and when.
Keyword expansion can be modified when using the admin, add, checkout, export, and update commands. Options to admin and add modify the default keyword-expansion mode of a file. Options to checkout, export, and update modify the keyword-expansion mode of the current sandbox version of a file, overriding the file's default mode. When checkout and update create or modify a sandbox, they can set a keyword-expansion mode to apply to the copy of a file in that sandbox. Some commands (such as diff ) have temporary keyword-expansion modes that apply while the command is running.
Keyword-expansion modes are set with -k or -A flags to the relevant command. These are the most common modes:
Inhibit keyword expansion and line-ending conversion. Use this keyword-expansion mode to signal that a file is binary.
Generate only the keyword name, not the name and the value. Use this mode when merging different (nonbinary) versions of a file, to prevent keyword substitution from creating spurious merge errors.
Generate the version of the keyword string that was present just before the file was last committed, rather than as it should be with the modifications of the last commit. This mode is similar to the effect of -kb, but with line-ending conversion.
Generate only the value of the keyword, rather than the name and value. This mode is most useful with cvs export, but do not use it for binary files. Once a keyword name is removed from a file, further expansions are not possible unless the word is replaced.
Reset all sandbox-specific dates, tags, and keyword-expansion modes to the file's defaults, and retrieve the latest revision (the revision at the head of the trunk). This mode is used only for checkout and update.