% 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 and may be turned off anytime.

Substitution takes place on every commit and update of the working
repository.

Caveat: "hg import" might fail if the patches were exported from a
repo with a different/no keyword setup, whereas "hg unbundle" is
safe.

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

Example:
     [keyword]
     # filename patterns for expansion are configured in this section
     # files matching patterns with value 'ignore' are ignored
     **.py =          ## expand keywords in all python files
     x* = ignore      ## but ignore files matching "x*"
     ...
     [keywordmaps]
     # custom hg template maps _replace_ the CVS-like default ones
     HGdate = {date|rfc822date}
     lastlog = {desc} ## same as {desc|firstline} in this context
     checked in by = {author}
     ...

If no [keywordmaps] are configured the extension falls back on the
following defaults:

     Revision: changeset id
     Author: username
     Date: %Y/%m/%d %H:%M:%S      ## [UTC]
     RCSFile: basename,v
     Source: /path/to/basename,v
     Id: basename,v csetid %Y/%m/%d %H:%M:%S username
     Header: /path/to/basename,v csetid %Y/%m/%d %H:%M:%S username

no commands defined
% cat
expand $Id$
expand $Id$
ignore $Id$
% default keyword expansion
% commit
adding a
adding b
adding sym
a
b
sym
overwriting a expanding keywords
% status
% cat
expand $Id: a,v 126ec311add6 1970/01/01 00:00:00 user $
expand $Id: a,v 126ec311add6 1970/01/01 00:00:00 user $
ignore $Id$
% hg cat
expand $Id: a,v 126ec311add6 1970/01/01 00:00:00 user $
ignore $Id$
a
% update
3 files updated, 0 files merged, 0 files removed, 0 files unresolved
% cat
expand $Id: a,v 126ec311add6 1970/01/01 00:00:00 user $
expand $Id: a,v 126ec311add6 1970/01/01 00:00:00 user $
ignore $Id$
% custom keyword expansion
% cat
expand $Id: a,v 126ec311add6 1970/01/01 00:00:00 user $
expand $Id: a,v 126ec311add6 1970/01/01 00:00:00 user $
ignore $Id$
% hg cat
expand $Id: a 126ec311add6 Thu, 01 Jan 1970 00:00:00 +0000 user $
ignore $Id$
a
% commit
a
overwriting a expanding keywords
% status
% cat
expand $Id: a 6022c13396d3 Thu, 01 Jan 1970 00:00:01 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
expand $Id: a 6022c13396d3 Thu, 01 Jan 1970 00:00:01 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
% hg cat
expand $Id: a 6022c13396d3 Thu, 01 Jan 1970 00:00:01 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
a
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
searching for changes
changeset:   1:6022c13396d3
tag:         tip
user:        User Name <user@example.com>
date:        Thu Jan 01 00:00:01 1970 +0000
summary:     firstline

% switch off expansion
% cat
expand $Id: a 6022c13396d3 Thu, 01 Jan 1970 00:00:01 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
expand $Id: a 6022c13396d3 Thu, 01 Jan 1970 00:00:01 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
% hg cat
expand $Id$
$Xinfo$
ignore $Id$
a
% update
3 files updated, 0 files merged, 0 files removed, 0 files unresolved
% cat
expand $Id$
$Xinfo$
expand $Id$
$Xinfo$
ignore $Id$