% 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 revision checked out!

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