3.9. Keywords CVS recognizes keywords that you can embed in any source file other than a binary file. When CVS finds a keyword in a file that it is checking out, it expands the keyword to provide metadata about the latest revision of the file. CVS keywords take the following form: $Keyword$ Example 3-21 shows a file that includes CVS keywords. Example 3-21. CVS keywords| # Makefile for the Wizzard project # First created by J Vesperman, 1 September 2002 # # Current revision $Revision$ # On branch $Name$ # Latest change by $Author$ # 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$ |
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. Example 3-22. Expanded keywords| # Current revision $Revision$ # On branch $Name$ # Latest change by $Author$ on $Date$ # Initial declarations CC=gcc SUBDIRS = man doc src lib . . . # Log record for Makefile changes: # $Log$ # Revision 1.6 2004/04/16 16:15:52 chodacki # sfcleanup fixes # # 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 |
The full list of possible keywords is provided in Chapter 11. These are the most commonly used keywords: 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 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. Name The tag name under which the file was checked out. 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. | In CVS 1.11.5, the Name keyword is updated only on a fresh checkout, and displays only static tags. This problem may be corrected in a later version. |
|
Log Commit messages, dates, and author, recorded in the file itself. Any characters that prefix the keyword are also used to prefix log lines; this feature 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 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 prevent users from 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. 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. 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. | CVS 1.12.2 adds the ability to configure your own local keywords. See Chapter 6 for more information. |
|
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: -kb Inhibits 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. Line-ending conversion can corrupt binary files. |
|
-kk Generates 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. -ko Generates 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. -kv Generates 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. (Note that once a keyword name is removed from a file, further expansions are not possible unless the word is replaced: don't use this with cvs checkout.) -A Resets all sandbox-specific dates, tags, and keyword-expansion modes to the file's defaults, and retrieves the latest revision (the revision at the head of the trunk). This mode is used only for checkout and update. |