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

The exansion works in 2 modes:
    1) working mode: substitution takes place on every commit and
       update of the working repository.
    2) archive mode: substitution is only triggered by "hg archive".

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
     **.py =          ## expand keywords in all python files
     x* = ignore      ## but ignore files matching "x*"
     ** = archive     ## keywords in all textfiles are expanded
                      ## when creating a distribution
     y* = noarchive   ## keywords in files matching "y*" are not expanded
                      ## on archive creation
     ...
     [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$
ignore $Id$
archive $Id$
expand $Id$
% default keyword expansion
% commit
adding a
adding b
adding c
adding sym
a
b
c
sym
overwriting a expanding keywords
% status
% cat
expand $Id: a,v 99e97605039e 1970/01/01 00:00:00 user $
ignore $Id$
archive $Id$
expand $Id: a,v 99e97605039e 1970/01/01 00:00:00 user $
% hg cat
expand $Id: a,v 99e97605039e 1970/01/01 00:00:00 user $
archive $Id$
ignore $Id$
a
% update
4 files updated, 0 files merged, 0 files removed, 0 files unresolved
% cat
expand $Id: a,v 99e97605039e 1970/01/01 00:00:00 user $
ignore $Id$
archive $Id$
expand $Id: a,v 99e97605039e 1970/01/01 00:00:00 user $
% archive
% cat
expand $Id$
ignore $Id$
archive $Id: c,v 99e97605039e 1970/01/01 00:00:00 user $
a
% custom keyword expansion
% cat
expand $Id: a,v 99e97605039e 1970/01/01 00:00:00 user $
ignore $Id$
archive $Id$
expand $Id: a,v 99e97605039e 1970/01/01 00:00:00 user $
% hg cat
expand $Id: a 99e97605039e Thu, 01 Jan 1970 00:00:00 +0000 user $
archive $Id$
ignore $Id$
a
% commit
a
overwriting a expanding keywords
% status
% cat
expand $Id: a 001dbcdc5258 Thu, 01 Jan 1970 00:00:01 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
archive $Id$
expand $Id: a 001dbcdc5258 Thu, 01 Jan 1970 00:00:01 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
% hg cat
expand $Id: a 001dbcdc5258 Thu, 01 Jan 1970 00:00:01 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
archive $Id$
ignore $Id$
a
requesting all changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 4 changes to 4 files
4 files updated, 0 files merged, 0 files removed, 0 files unresolved
% incoming
searching for changes
changeset:   1:001dbcdc5258
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 001dbcdc5258 Thu, 01 Jan 1970 00:00:01 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
ignore $Id$
archive $Id$
expand $Id: a 001dbcdc5258 Thu, 01 Jan 1970 00:00:01 +0000 user $
$Xinfo: User Name <user@example.com>: firstline $
% hg cat
expand $Id$
$Xinfo$
archive $Id$
ignore $Id$
a
% update
4 files updated, 0 files merged, 0 files removed, 0 files unresolved
% cat
expand $Id$
$Xinfo$
ignore $Id$
archive $Id$
expand $Id$
$Xinfo$