% help
keyword extension - keyword expansion in local repositories
This extension expands RCS/CVS-like or self-customized $Keywords$
in tracked text files selected by your configuration.
Keywords are only expanded in local repositories and not stored in
the change history. The mechanism can be regarded as a convenience
for the current user or for archive distribution.
Configuration is done in the [keyword] and [keywordmaps] sections
of hgrc files.
Example:
    [keyword]
    # expand keywords in every python file except those matching "x*"
    **.py =
    x*    = ignore
Note: the more specific you are in your filename patterns
      the less you lose speed in huge repos.
For [keywordmaps] template mapping and expansion demonstration and
control run "hg kwdemo".
An additional date template filter {date|utcdate} is provided.
The default template mappings (view with "hg kwdemo -d") can be replaced
with customized keywords and templates.
Again, run "hg kwdemo" to control the results of your config changes.
Before changing/disabling active keywords, run "hg kwshrink" to avoid
the risk of inadvertedly storing expanded keywords in the change history.
To force expansion after enabling it, or a configuration change, run
"hg kwexpand".
Expansions spanning more than one line and incremental expansions,
like CVS' $Log$, are not supported. A keyword template map
"Log = {desc}" expands to the first line of the changeset description.
Caveat: "hg import" fails if the patch context contains an active
        keyword. In that case run "hg kwshrink", and then reimport.
        Or, better, use bundle/unbundle to share changes.
 kwdemo     print [keywordmaps] configuration and an expansion example
 kwexpand   expand keywords in working directory
 kwshrink   revert expanded keywords in working directory
% hg kwdemo
[extensions]
hgext.keyword = 
[keyword]
* = 
b = ignore
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}
$RCSFile: demo.txt,v $
$Author: test $
$Header: /TMP/demo.txt,v xxxxxxxxxxxx 2000/00/00 00:00:00 test $
$Source: /TMP/demo.txt,v $
$Date: 2000/00/00 00:00:00 $
$Id: demo.txt,v xxxxxxxxxxxx 2000/00/00 00:00:00 test $
$Revision: xxxxxxxxxxxx $
[extensions]
hgext.keyword = 
[keyword]
* = 
b = ignore
demo.txt = 
[keywordmaps]
Branch = {branches}
$Branch: demobranch $
% kwshrink should abort in empty/invalid repo
abort: no revision checked out!
% cat
expand $Id$
ignore $Id$
% default keyword expansion
% commit
adding a
adding b
a
b
overwriting a expanding keywords
% status
% identify
65cbcc9534b0
% cat
expand $Id: a,v 65cbcc9534b0 1970/01/01 00:00:00 user $
ignore $Id$
% hg cat
expand $Id: a,v 65cbcc9534b0 1970/01/01 00:00:00 user $
ignore $Id$
% touch
% status
% update
2 files updated, 0 files merged, 0 files removed, 0 files unresolved
% cat
expand $Id: a,v 65cbcc9534b0 1970/01/01 00:00:00 user $
ignore $Id$
% copy
% commit
c
 c: copy a:e6cc15c9eb5fd3c09ec691b667cf6ccd6dfb936e
overwriting c expanding keywords
% cat a c
expand $Id: a,v 65cbcc9534b0 1970/01/01 00:00:00 user $
expand $Id: c,v 9460ba56f8d0 1970/01/01 00:00:01 user $
% touch copied c
% status
% rollback
rolling back last transaction
% status
A c
% update -C
0 files updated, 0 files merged, 1 files removed, 0 files unresolved
% custom keyword expansion
% try with kwdemo
[extensions]
hgext.keyword = 
[keyword]
* = 
b = ignore
demo.txt = 
[keywordmaps]
Xinfo = {author}: {desc}
$Xinfo: test: hg keyword config and expansion example $
% cat
expand $Id: a,v 65cbcc9534b0 1970/01/01 00:00:00 user $
ignore $Id$
% hg cat
expand $Id: a 65cbcc9534b0 Thu, 01 Jan 1970 00:00:00 +0000 user $
ignore $Id$
% interrupted commit
transaction abort!
rollback completed
% status
M a
? log
% commit
a
overwriting a expanding keywords
% status
% cat
expand $Id: a 6ade9dd7b017 Thu, 01 Jan 1970 00:00:02 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
% hg cat
expand $Id: a 6ade9dd7b017 Thu, 01 Jan 1970 00:00:02 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
% remove
% status
% rollback
rolling back last transaction
% status
R a
% revert a
% cat a
expand $Id: a 6ade9dd7b017 Thu, 01 Jan 1970 00:00:02 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
% clone to test incoming
requesting all changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 2 changes to 2 files
2 files updated, 0 files merged, 0 files removed, 0 files unresolved
% incoming
searching for changes
changeset:   1:6ade9dd7b017
tag:         tip
user:        User Name <user@example.com>
date:        Thu Jan 01 00:00:02 1970 +0000
summary:     firstline

% switch off expansion
% kwshrink
overwriting a shrinking keywords
% cat
expand $Id$
$Xinfo$
ignore $Id$
% hg cat
expand $Id: a 6ade9dd7b017 Thu, 01 Jan 1970 00:00:02 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
% cat
expand $Id$
$Xinfo$
ignore $Id$
% hg cat
expand $Id$
$Xinfo$
ignore $Id$