Enabling Keyword Expansion

Keyword expansion and EOL conversion work correctly for UTF-8 unicode files, which previously could be corrupted on check-in. However, EOL conversion is not supported for UTF-16 or UTF-32 unicode files. The Cross-Platform Client allows you to select a file encoding as you check out a file.

StarTeam supports Log and History Keywords from the StarTeam Server and from the MPX Cache Agent.

Caution: Never use a keyword in a revision comment, as it will be expanded during the keyword expansion process.

To enable keyword expansion, do the following:

  1. Choose Project > Properties.

    The Project Properties dialog box opens.

  2. Click the Options tab.

  3. Check the Keyword Expansion check box to enable keyword expansion and use keywords in your text files.

    This check box applies to files added or checked in from StarTeam or from StarTeam integrations with third-party applications.

  4. In Expand Keywords for These File Extensions field, type the file extensions (for example, .bat, .cpp) for which you want to use keywords.

    You can use a space, comma, or semicolon as keyword delimiters. The file extensions list can contain a maximum of 254 characters. If you leave this text box blank, no keywords will be expanded.

Back to top

StarTeam Keywords

By enabling keyword expansion for a project, you can embed keywords within text files. These keywords are automatically expanded during file check-outs, to provide file and revision information within the file. You should use only one keyword per line.

The following table provides descriptions of keywords for use in keyword expansion.

Item Description
$Author$

User who checked in the revision.

$Date$ and $DateUTC$

Date and time stamps for the revision. $DateUTC$ is the same as $Date$ except that a UTC time replaces the local time. UTC times end in a “Z,” which makes them readily identifiable.

$Header$ and $HeaderUTC$

Combinations of Workfile, Revision, Date, and Author. $HeaderUTC$ is the same as $Header$ except that a UTC time replaces the local time. UTC times end in a “Z” which makes them readily identifiable.

For Java users, $Header$ can cause problems if \u (for unicode) appears in the expanded header. For example, suppose that a file named foo.java is stored in D:\util. The first time you compile it with $Header$, the header is expanded to:

$Header: D:\util\foo.java, 1, 7/27/11 11:05:48 AM, StarTeam Server Administrator$

Even though this header is contained in a Java comment, the Java compiler always looks for \u. The second time you compile foo.java, a compiler error occurs.

$History$

Added to the source file, typically within a comment field. The $History$ keyword creates a history record for the latest (tip) revision and places the information after the keyword. For example, after the file is checked-out for the first time, the file would contain the following: 

// ...
// $History
// 1 YourProject 1.0 2011-11-19 00:06:57Z Joe Smith
// This is a revision comment.
// $

StarTeam adds the history information to the file and places it outside of the “$” signs so that it becomes a versioned part of the file. Since the history records become part of the versioned file content, you can delete extra or excessive history records at any time. If this file is modified and checked-in, any subsequent check-out adds one additional record immediately after the $History$ keyword: 

// $History
// 2 YourProject 1.0 2012-06-01 00:06:57Z Joe Smith
// This is a another revision comment.
// $
// 1 YourProject 1.0 2011-11-19 00:06:57Z Joe Smith
// This is a revision comment.

StarTeam uses the MD5 and local file timestamp of the post-expanded file for sync records. Accordingly, when you check-out a tip revision, StarTeam reports a current status for the file even though a compare tool would show an additional history record in the locally-stored file as compared to the version of the file saved on the StarTeam Server.

Important: Do not delete the standalone // $ line. StarTeam places the most recent historical revision information within the // $ delimiter. The rest of the revision entries are outside of this delimiter. StarTeam does not recognize the $History$ keyword if you remove this line.

$Id$

Similar to $HeaderUTC$ except that it is a combination of Workfile, the branch revision number (preceded by "v" for version; for example, v 1.2.1.0), UTC time, and Author. The branch revision number is in dot notation.

$Locker$

User who has the file exclusively locked (if any).

$Log$, $Log[x]$, $LogUTC$, and $LogUTC[x]$

File change history. $Log$ is a special keyword because it expands to a multiline entry. The $Log$ keyword expands to include information for each revision of the file. Revision history includes Revision Number, Date, Author, and Reason for Check In.

Use $Log$ to retain entries for each revision within the file.

Use $Log[x]$ to limit the number of revisions for which entries are retained. Replace x with the number of entries to be retained. For example, $Log[8] saves the entries for the most recent 8 revisions. If you replace x with a number less than 1 or with a non-numeric character, StarTeam ignores x and retains all entries (as with $Log$).

$LogUTC$ and $LogUTC[x]$ are the same as $Log$ and $Log[x]$ except that a UTC time replaces the local time. UTC times end in a “Z”.

$NoKeywords$

Turn off keyword expansion for the rest of the file.

$Project$

Name of the project.

$Revision$

Revision number (an integer).

$Folder$

Name of the folder.

$Workfile$

Unqualified name of the working file (for example, foo.cpp).

Caution: Never use a keyword in a revision comment, as it will be expanded during the keyword expansion process.

Back to top