% help
keyword extension - keyword expansion in local repositories

This extension expands RCS/CVS-like or self-customized $Keywords$
in the text files selected by your configuration.

Keywords are only expanded in local repositories and not logged by
Mercurial internally. The mechanism can be regarded as a convenience
for the current user or archive distribution.

Configuration is done in the [keyword] and [keywordmaps] sections of
hgrc files.

Example:
    [extensions]
    hgext.keyword =

    [keyword]
    # expand keywords in every python file except those matching "x*"
    **.py =
    x* = ignore

Note: the more specific you are in your [keyword] filename patterns
      the less you lose speed in huge repos.

For a [keywordmaps] template mapping and expansion demonstration
run "hg kwdemo".

An additional date template filter {date|utcdate} is provided.

You can replace the default template mappings with customized keywords
and templates of your choice.
Again, run "hg kwdemo" to control the results of your config changes.

When you change keyword configuration, especially the active keywords,
and do not want to store expanded keywords in change history, run
"hg kwshrink", and then change configuration.

Expansions spanning more than one line and incremental exapansions
(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", reimport, and then
        "hg kwexpand".
        Or, better, use bundle/unbundle to share changes.

list of commands (use "hg help -v keyword" to show aliases and global options):

 kwdemo     print [keywordmaps] configuration and an expansion example
 kwexpand   expand keywords in working directory
 kwshrink   revert expanded keywords in working directory
% hg kwdemo
[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}
$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 $
% kwshrink should abort in empty/invalid repo
abort: no changeset found!
% 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
[keyword]
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
abort: edit failed: false exited with status 1
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$
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$