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