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

 kwdemo     print [keywordmaps] configuration and an expansion example

 kwexpand   expand keywords in working directory

 kwshrink   revert expanded keywords in working directory

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

% kwshrink should abort in empty/invalid repo

abort: no revision checked out!

% cat

expand $Id$

ignore $Id$

% default keyword expansion

% commit

adding a

adding b

a

b

overwriting a expanding keywords

% status

% identify

% cat

ignore $Id$

% hg cat

ignore $Id$

% touch

% status

% update

2 files updated, 0 files merged, 0 files removed, 0 files unresolved

% cat

ignore $Id$

% copy

% commit

c

overwriting c expanding keywords

% cat a c

% 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

[extensions]

hgext.keyword = 

[keyword]

* = 

b = ignore

demo.txt = 

[keywordmaps]

Xinfo = {author}: {desc}

$Xinfo: test: hg keyword config and expansion example $

% cat

ignore $Id$

% hg cat

ignore $Id$

% interrupted commit

transaction abort!

rollback completed

% status

M a

? log

% commit

a

overwriting a expanding keywords

% status

% cat

$Xinfo: User Name <user@example.com>: firstline $

ignore $Id$

% hg cat

$Xinfo: User Name <user@example.com>: firstline $

ignore $Id$

% remove

% status

% rollback

rolling back last transaction

% status

R a

% revert a

% cat a

$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 2 changes to 2 files

2 files updated, 0 files merged, 0 files removed, 0 files unresolved

% incoming

searching for changes

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

$Xinfo: User Name <user@example.com>: firstline $

ignore $Id$

% cat

expand $Id$

$Xinfo$

ignore $Id$

% hg cat

expand $Id$

$Xinfo$

ignore $Id$