% 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
 kwfiles    print files currently configured for keyword expansion
 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 $
% do not expand debug templates
ADD = empty{file_adds}
$ADD$
$ADD: empty $
% kwshrink should exit silently in empty/invalid repo
% cat
expand $Id$
do not process $Id:
xxx $
ignore $Id$
% default keyword expansion
% commit
adding a
adding b
a
b
overwriting a expanding keywords
% status
% identify
7f0665a496fd
% cat
expand $Id: a,v 7f0665a496fd 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
ignore $Id$
% hg cat
expand $Id: a,v 7f0665a496fd 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
ignore $Id$
% touch
% status
% update
2 files updated, 0 files merged, 0 files removed, 0 files unresolved
% cat
expand $Id: a,v 7f0665a496fd 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
ignore $Id$
% copy
% kwfiles added
a
c
% commit
c
 c: copy a:0045e12f6c5791aac80ca6cbfd97709a88307292
overwriting c expanding keywords
% cat a c
expand $Id: a,v 7f0665a496fd 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
expand $Id: c,v 6a127771f5db 1970/01/01 00:00:01 user $
do not process $Id:
xxx $
% touch copied c after 1 second
% status
% kwfiles
a
c
% diff --rev
diff -r 7f0665a496fd c
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -0,0 +1,3 @@
+expand $Id: c,v 6a127771f5db 1970/01/01 00:00:01 user $
+do not process $Id:
+xxx $
% 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 7f0665a496fd 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
ignore $Id$
% hg cat
expand $Id: a 7f0665a496fd Thu, 01 Jan 1970 00:00:00 +0000 user $
do not process $Id:
xxx $
ignore $Id$
% interrupted commit
transaction abort!
rollback completed
% status
M a
? log
% commit
a
overwriting a expanding keywords
% status
% cat
expand $Id: a 576a35651b0a Thu, 01 Jan 1970 00:00:02 +0000 user $
do not process $Id:
xxx $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
% hg cat
expand $Id: a 576a35651b0a Thu, 01 Jan 1970 00:00:02 +0000 user $
do not process $Id:
xxx $
$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 576a35651b0a Thu, 01 Jan 1970 00:00:02 +0000 user $
do not process $Id:
xxx $
$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:576a35651b0a
tag:         tip
user:        User Name <user@example.com>
date:        Thu Jan 01 00:00:02 1970 +0000
summary:     firstline

% pathto for kwexpand/kwshrink
% copy
x/a
 x/a: copy a:779c764182ce5d43e2b1eb66ce06d7b47bfe342e
overwriting x/a expanding keywords
% cat a
expand $Id: x/a 2d19a72f00da Thu, 01 Jan 1970 00:00:03 +0000 user $
do not process $Id:
xxx $
$Xinfo: User Name <user@example.com>: xa $
% kwshrink a
overwriting x/a shrinking keywords
% cat a
expand $Id$
do not process $Id:
xxx $
$Xinfo$
% switch off expansion
% kwshrink with unknown file u
overwriting a shrinking keywords
overwriting x/a shrinking keywords
% cat
expand $Id$
do not process $Id:
xxx $
$Xinfo$
ignore $Id$
% hg cat
expand $Id: a 576a35651b0a Thu, 01 Jan 1970 00:00:02 +0000 user $
do not process $Id:
xxx $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
% cat
expand $Id$
do not process $Id:
xxx $
$Xinfo$
ignore $Id$
% hg cat
expand $Id$
do not process $Id:
xxx $
$Xinfo$
ignore $Id$