Expand Keywords (EXPANDKEYWORDS) (see also)
Keywords are a useful way to place important version control information inside the file itself. Typically, you use QVCS keywords in text files to provide ongoing audit trails within your project source code. However, you can also use most QVCS keywords in binary files, provided they aren't sensitive to content changes.
Keywords are controlled by the EXPANDKEYWORDS attribute, which tells QVCS whether to expand any keywords contained in a file. If EXPANDKEYWORDS is enabled, QVCS expands any keywords present when fetching a revision into the work file. When storing a revision into the archive, the keywords in the stored revision will be contracted, while the work file will be edited to make sure any expanded keywords are up-to-date. This necessarily changes the edit date of the work file to the time when you checked in the revision.
QVCS recognizes how to contract keywords by searching for the trailing $ character after the expansion string. In order for the expand and contract algorithms to work correctly, you should be careful to leave the final $ character in tact.
By default, keyword expansion is disabled.
QVCS supports the following keywords:
- $Author$ expands to the author of the changes of the current revision; i.e. the person who stored the revision that the current work file is a copy of. $Author$ is different from the $Owner$ keyword, in that $Author$ is derived from the current revision, whereas $Owner$ is the person who created the QVCS archive.
- $Comment$ is different from other keywords in that it contracts rather than expands. You use the $Comment$ keyword to embed revision comments in a file as you edit it. When you then store the new revision of the file, any $Comment$ keywords present in the file will be extracted from the file and used as revision comments. There's no limit to the number of $Comment$ strings you can embed within your work file, nor does it matter where you place them, making it easy to add a comment for a particular edit as you make the change rather than trying to remember everything you altered later.
When stored as comments, separate $Comment$ keywords in the work file are separated from one another by a carriage-return/linefeed combination, and as a block are appended to the revision comment you enter from the command line (via the -comment option), or they are appended to the revision comment that you enter at the ':' prompt. In Qwin, they are appended to the revision comment that you enter in the "Description of changes:" edit box in the Check-in dialog. The syntax for entering a comment is much like the syntax of an expanded keyword:
$Comment: This comment will become part of a revision description.$
The $Comment$ keyword can only be used effectively for QVCS archives that have EXPANDKEYWORDS enabled. After a work file containing $Comment$ keywords is stored, the $Comment$ string is completely removed from the work file. That is, when you next check out the revision, the $Comment$ string and comment will have been removed.
- $Copyright$ expands to $Copyright © followed by the range of years for the revisions of the file, followed by the copyright message that you define via the Settings tab of the Project→Edit Settings... dialog.
- $Date$ expands to $Date: plus the date of the file used to create the current revision. For example:
$Date: Mon Jun 2 15:27:00 2007 $
The expanded date is the edit date of the work file used to create the revision, not the date when the revision was created.
- $Endlog$ marks the end of an expanded log. You should NOT use this keyword. It's used by QVCS to mark the end of the expanded log. Do not delete it from your work file either, QVCS will do that automatically when you put your work file back into the QVCS archive.
- $Filename$ expands to $Filename: plus the full pathname of the work file into which the revision is being retrieved. For example:
$Filename: c:\foo\source\foobar.c $
- $Header$ expands to $Header: plus the name of the work file, the current revision, the file date, and the file owner. The $Header$ combines in a single keyword the same information that you'd get if you used $Filename$, $Revision$, $Date$, and $Owner$ separately. For example:
$Header: foobar.c Revision:1.0.1.2 Fri Apr 10 22:35:11 2007 John Smith $
- $Log$ expands to $Log: plus the full path name of the QVCS archive. On the next line, the module description begins. After the module description, the revision comments contained in the QVCS archive (preceded by the comment prefix string) appear in reverse chronological order from the current revision all the way back to the oldest revision contained in the QVCS archive. After the log information for the oldest revision, $Endlog$ is inserted to mark the end of the log information. For example a portion of a log expansion for a C++ header file could look like:
// $Log: \\Qumadell\VersionControl\qvcsroot\Include\qvcs.i $
//
// Master header file for QVCS.
//
// Revision 1.34 by: Jim Voris Rev date: 4/15/2005 8:56:18 PM
// Minor edit to get status corrected.
//
// Revision 1.33 by: Jim Voris Rev date: 4/7/2005 4:21:48 PM
// Change copyright character.
//
// Revision 1.32 by: Jim Voris Rev date: 3/14/2005 4:58:13 PM
// Add #define for qvcsDEFAULT_REVISION
//
// Revision 1.31 by: JimVoris Rev date: 1/28/2005 11:45:35 AM
// Update copyright to 2005
//
// Revision 1.30 by: JimVoris Rev date: 5/15/2004 3:28:48 PM
// Update copyright.
...
...
//
// $Endlog$
QVCS uses the $Endlog$ mark when it contracts the $Log$ keyword before storing the revision in the QVCS archive. The QVCS archive's comment prefix string is used during expansion of the $Log$ keyword. QVCS uses the comment prefix string to prefix each log line that it inserts into the work file as it is extracted from the QVCS archive. In the example above, the comment prefix is "// ".
- $LogX$ is similar to the $Log$ keyword except that it displays only the X most recent revision descriptions found in the QVCS archive. For example, if you wanted to see just the 5 most recent revision descriptions at the top of your source file, you'd use $Log5$ as the keyword. To see just the 10 most recent revision descriptions, you'd use $Log10$, etc.
- $Logfile$ expands to the full path name of the QVCS archive. This is identical to the expanded filename that appears as the first line in the expansion of the $Log$ and $LogX$ keywords.
- $Owner$ expands to $Owner: plus the owner of the QVCS archive (i.e. the name of the person who created the QVCS archive). For example:
$Owner: JoeSmith $
- $Project$ expands to $Project: plus the name of the current project. For example:
$Project: QVCS Source Code $
- $Revision$ expands to $Revision: plus the revision number of the current revision. For example:
$Revision: 1.2 $
- $Version$ expands to $Version: plus the version or label string associated with the current revision. If there is no version string for the current revision, it expands to NONE. $Version$ is useful for imbedding the version string into code. For example, in C, you might use the following statement to embed a global version string that you can then update easily with QVCS:
char *pcgVersionString = "$Version$";
If you label the file containing this code and then retrieve the revision from the QVCS archive, the code looks like:
char *pcgVersionString = "$Version: versionstring $";
where versionstring is whatever you use for the version string when you label the revision.
- $Label$ expands to $Label: plus the label associated with the current revision. The $Label$ keyword is synonymous with the $Version$ keyword.
- $VER$ expands to $VER: the name of the source file (minus file extension), plus the version or label string associated with the current revision. If there is no version string for the current revision, the version string portion expands to NONE.. All QVCS command line executables are marked with this keyword. For example, you can find out the version of qget.exe by typing the following into the command line:
qident qget.exe
To delete keywords from a work file, just delete everything between the the first and last $ characters, including the $ characters themselves. For expanded $Log$ and $LogX$ keywords, this could be a little tedious. To make it easier, just be sure to disable keyword expansion when you fetch the work file, either by unchecking the "Expand Keywords" check box in the QWin Check-out dialog, or by using the -a EXPANDWORDS=NO switch on the command line. This will result in all keywords existing in the work file in contracted form.
Using Keywords in a Binary File
To add a keyword to a text file, simply add the keyword in the $keyword$ form, $Log$ for example. For binary files, it isn't quite so simple. First, you must be sure to use keywords only in those binary files which aren't sensitive to content changes: when QVCS expands keywords for text files, it changes the size of the file; when it expands keywords for a binary file, it changes the content of some characters in the file, but it doesn't change the size of the binary file.
To add a keyword to a binary work file, you must add it in "expanded" form. For example, to add a $Date$ keyword into a binary file, you would edit the file (assuming you can!) to have the following line for the Date keyword:
$Date: $
making sure to include enough spaces between the : and the trailing $ to contain the expanded date. QVCS will replace the spaces with the expanded value of the keyword, leaving the size of the work file the same. Note that you can put more room into the expansion area if you want, and QVCS will just end up padding the information with the space character. However, if you don't leave enough room, the expanded keyword will end up truncated.
Keyword expansion for binary files can work well for embedding QVCS keywords in word processor files, or other similar files that are stored in binary format. For example, you can usefully embed QVCS keywords in Word 6.0 files.
For binary work files, the $Log$ and $LogX$ keywords are ignored, since the exact size of an expanded log can vary widely.
QVCS Attributes
See also: the tutorial sections on using keywords in a text file.
|
