Keyword Expansion extension
This extension is not being distributed along with Mercurial.
Author: Christian Ebert
Download site: [http://www.blacktrash.org/hg/hgkeyword/ keyword expansion repository].
Mirror of crew repo plus keyword extension: [http://www.blacktrash.org/hg/hg-crew-keyword/ Mercurial crew + keyword].
Overview
This extension allows the expansion of RCS/CVS-like and user defined keys in text files tracked by Mercurial. Expansion takes place in the working directory or/and when creating a distribution using "hg archive".
Configuration
To enable this extension add it to the '[extensions]' stanza in the hgrc file:
[extensions] hgext.keyword= #or, if keyword.py is not in the hgext folder: #keyword=/path/to/keyword.py
Additional configuration is done in the [keyword] and [keywordmaps] sections in your configuration file:
# filename patterns for expansion are configured in this section
[keyword]
# expand keywords in all python files in working dir
**.py =
# do not expand keywords in files matching "x*" in working dir
x* = ignore
...
# in case you prefer your own keyword maps over the cvs-like defaults:
# using "key-to-be-expanded = value" lines, where values are taken from the available Mercurial template names.
# an additional filter "utcdate" is provided to get "%Y/%m/%d %H:%M:%S" date format.
[keywordmaps]
HGdate = {date|rfc822date}
lastlog = {desc} ## same as {desc|firstline} in this context
checked in by = {author}
Usage
The main functionality of the extension is done in background by automatically expanding the defined keys (or default ones), without user interaction.
However, the extension provides the following convenience commands:
kwdemo
To get an idea what the extension actually does and/or to test your customizations (templates are rather sparsely documented), run "hg kwdemo".
Example output of "hg kwdemo --default":
config with default keyword template maps:
[keyword]
demo.txt =
[keywordmaps]
RCSFile = {file|basename},v
Author = {author|user}
Header = {root}/{file},v {node|short} {date|utcdate} {author|user}
Source = {root}/{file},v
Date = {date|utcdate}
Id = {file|basename},v {node|short} {date|utcdate} {author|user}
Revision = {node|short}
default keywords expanded:
$RCSFile: demo.txt,v $
$Author: blacktrash $
$Header: /tmp/kwdemo.Oz46E2/demo.txt,v 2ad3dcb8d811 2007/07/17 12:00:47 blacktrash $
$Source: /tmp/kwdemo.Oz46E2/demo.txt,v $
$Date: 2007/07/17 12:00:47 $
$Id: demo.txt,v 2ad3dcb8d811 2007/07/17 12:00:47 blacktrash $
$Revision: 2ad3dcb8d811 $
kwshrink, kwexpand
Run "hg kwshrink" before eg. changing the currently active keywords, if you don't want the expanded keywords stored in the change history.
Expanding keywords only in the current working copy allows you to share changes with other repos that do not have the same or no keyword setup. This can sometimes cause a problem with "hg import" if the change context contains an active keyword. To overcome this run "hg kwshrink", (re)import, "hg kwexpand". Or, better, use bundle/unbundle to share changes.