% 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.

list of commands:

 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

use "hg -v help keyword" to show aliases and global options
% 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 $
expand $Id$
do not process $Id:
xxx $
ignore $Id$
% default keyword expansion
% commit
adding a
adding b
adding sym
a
b
sym
overwriting a expanding keywords
% status
% identify
f782df5f9602
% cat
expand $Id: a,v f782df5f9602 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
expand $Id: a,v f782df5f9602 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
ignore $Id$
% hg cat
expand $Id: a,v f782df5f9602 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
ignore $Id$
a
% touch
% status
% update
3 files updated, 0 files merged, 0 files removed, 0 files unresolved
% cat
expand $Id: a,v f782df5f9602 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
expand $Id: a,v f782df5f9602 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 f782df5f9602 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
expand $Id: c,v 0ba462c0f077 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 f782df5f9602 c
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -0,0 +1,3 @@
+expand $Id: c,v 0ba462c0f077 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 f782df5f9602 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
expand $Id: a,v f782df5f9602 1970/01/01 00:00:00 user $
do not process $Id:
xxx $
ignore $Id$
% hg cat
expand $Id: a f782df5f9602 Thu, 01 Jan 1970 00:00:00 +0000 user $
do not process $Id:
xxx $
ignore $Id$
a
% interrupted commit
transaction abort!
rollback completed
abort: edit failed: false exited with status 1
% status
M a
? log
% commit
a
overwriting a expanding keywords
% status
% cat
expand $Id: a 0729690beff6 Thu, 01 Jan 1970 00:00:02 +0000 user $
do not process $Id:
xxx $
$Xinfo: User Name <user@example.com>: firstline $
expand $Id: a 0729690beff6 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 0729690beff6 Thu, 01 Jan 1970 00:00:02 +0000 user $
do not process $Id:
xxx $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
a
% remove
% status
% rollback
rolling back last transaction
% status
R a
% revert a
% cat a
expand $Id: a 0729690beff6 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 3 changes to 3 files
3 files updated, 0 files merged, 0 files removed, 0 files unresolved
% incoming
comparing with test-keyword/Test-a/../Test
searching for changes
changeset:   1:0729690beff6
tag:         tip
user:        User Name <user@example.com>
date:        Thu Jan 01 00:00:02 1970 +0000
summary:     firstline

% kwexpand/kwshrink on selected files
% copy a x/a
% kwexpand a
overwriting a expanding keywords
% kwexpand x/a should abort
abort: outstanding uncommitted changes in given files
x/a
 x/a: copy a:779c764182ce5d43e2b1eb66ce06d7b47bfe342e
overwriting x/a expanding keywords
% cat a
expand $Id: x/a f27c134d2d9b Thu, 01 Jan 1970 00:00:03 +0000 user $
do not process $Id:
xxx $
$Xinfo: User Name <user@example.com>: xa $
% kwshrink a inside directory x
overwriting x/a shrinking keywords
% cat a
expand $Id$
do not process $Id:
xxx $
$Xinfo$
% kwexpand nonexistent
nonexistent: No such file or directory
% 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$
expand $Id$
do not process $Id:
xxx $
$Xinfo$
ignore $Id$
% hg cat
expand $Id: a 0729690beff6 Thu, 01 Jan 1970 00:00:02 +0000 user $
do not process $Id:
xxx $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
a
% cat
expand $Id$
do not process $Id:
xxx $
$Xinfo$
expand $Id$
do not process $Id:
xxx $
$Xinfo$
ignore $Id$
% hg cat
expand $Id$
do not process $Id:
xxx $
$Xinfo$
ignore $Id$
a