% help

keyword extension - expand keywords in tracked files

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

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 inadvertently storing expanded keywords in the change

history.

To force expansion after enabling it, or a configuration change, run

"hg kwexpand".

Also, when committing with the record extension or using mq's qrecord,

be aware that keywords cannot be updated. Again, run "hg kwexpand" on

the files in question to update keyword expansions after all changes

have been checked in.

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: With Mercurial versions prior to 4574925db5c0 "hg import" might

        cause rejects 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 the working directory

 kwshrink   revert expanded keywords in the 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 exit silently in empty/invalid repo

pulling from test-keyword.hg

requesting all changes

adding changesets

adding manifests

adding file changes

added 1 changesets with 1 changes to 1 files

1 files updated, 0 files merged, 0 files removed, 0 files unresolved

% cat

expand $Id$

do not process $Id:

xxx $

ignore $Id$

% addremove

adding a

adding b

% status

A a

A b

% default keyword expansion including commit hook

% commit

a

b

overwriting a expanding keywords

running hook commit.test: cp a hooktest

% status

? hooktest

% identify

475643d17242

% cat

expand $Id: a,v 475643d17242 1970/01/01 00:00:00 user $

do not process $Id:

xxx $

ignore $Id$

% hg cat

expand $Id: a,v 475643d17242 1970/01/01 00:00:00 user $

do not process $Id:

xxx $

ignore $Id$

% diff a hooktest

% removing commit hook from config

% bundle

% pull from bundle

pulling from ../kw.hg

requesting all changes

adding changesets

adding manifests

adding file changes

added 2 changesets with 3 changes to 3 files

3 files updated, 0 files merged, 0 files removed, 0 files unresolved

% touch

% status

% update

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

% cat

expand $Id: a,v 475643d17242 1970/01/01 00:00:00 user $

do not process $Id:

xxx $

ignore $Id$

% check whether expansion is filewise

% commit c

adding c

% force expansion

overwriting a expanding keywords

overwriting c expanding keywords

% compare changenodes in a c

expand $Id: a,v 475643d17242 1970/01/01 00:00:00 user $

do not process $Id:

xxx $

$Id: c,v c08ff8b9d54e 1970/01/01 00:00:01 user $

tests for different changenodes

% qinit -c

% qimport

% qcommit

% keywords should not be expanded in patch

# HG changeset patch

# User User Name <user@example.com>

# Date 1 0

# Node ID c08ff8b9d54ebf87b428631bd34b3d8b69cbf72f

# Parent  475643d17242703d20c30af0fc52b30fd231c6f6

cndiff

diff -r 475643d17242 -r c08ff8b9d54e c

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000

+++ b/c	Thu Jan 01 00:00:01 1970 +0000

@@ -0,0 +1,2 @@

+$Id$

+tests for different changenodes

% qpop

Patch queue now empty

% qpush

applying mqtest.diff

Now at: mqtest.diff

% cat

$Id: c,v c08ff8b9d54e 1970/01/01 00:00:01 user $

tests for different changenodes

% qpop and move on

Patch queue now empty

% copy

% kwfiles added

a

c

% commit

c

 c: copy a:0045e12f6c5791aac80ca6cbfd97709a88307292

overwriting c expanding keywords

% cat a c

expand $Id: a,v 475643d17242 1970/01/01 00:00:00 user $

do not process $Id:

xxx $

expand $Id: c,v 1acf8f3ab611 1970/01/01 00:00:01 user $

do not process $Id:

xxx $

% touch copied c after 1 second

% status

% kwfiles

a

c

% diff --rev

diff -r 475643d17242 c

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000

@@ -0,0 +1,3 @@

+expand $Id$

+do not process $Id:

+xxx $

% 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

expand $Id: a,v 475643d17242 1970/01/01 00:00:00 user $

do not process $Id:

xxx $

ignore $Id$

% hg cat

expand $Id: a 475643d17242 Thu, 01 Jan 1970 00:00:00 +0000 user $

do not process $Id:

xxx $

ignore $Id$

% commit

a

overwriting a expanding keywords

% status

% verify

checking changesets

checking manifests

crosschecking files in changesets and manifests

checking files

3 files, 3 changesets, 4 total revisions

% cat

expand $Id: a 9ea11ce3ca13 Thu, 01 Jan 1970 00:00:02 +0000 user $

do not process $Id:

xxx $

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

ignore $Id$

% hg cat

expand $Id: a 9ea11ce3ca13 Thu, 01 Jan 1970 00:00:02 +0000 user $

do not process $Id:

xxx $

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

ignore $Id$

a

% annotate

1: expand $Id$

1: do not process $Id:

1: xxx $

2: $Xinfo$

% remove

% status

% rollback

rolling back last transaction

% status

R a

% revert a

% cat a

expand $Id: a 9ea11ce3ca13 Thu, 01 Jan 1970 00:00:02 +0000 user $

do not process $Id:

xxx $

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

% clone to test incoming

requesting all changes

adding changesets

adding manifests

adding file changes

added 2 changesets with 3 changes to 3 files

3 files updated, 0 files merged, 0 files removed, 0 files unresolved

% incoming

searching for changes

changeset:   2:9ea11ce3ca13

tag:         tip

user:        User Name <user@example.com>

date:        Thu Jan 01 00:00:02 1970 +0000

summary:     firstline

% kwexpand/kwshrink on selected files

% copy a x/a

% kwexpand a

overwriting a expanding keywords

% kwexpand x/a should abort

abort: outstanding uncommitted changes

x/a

 x/a: copy a:779c764182ce5d43e2b1eb66ce06d7b47bfe342e

overwriting x/a expanding keywords

% cat a

expand $Id: x/a 93c8b61c99cd Thu, 01 Jan 1970 00:00:03 +0000 user $

do not process $Id:

xxx $

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

% kwshrink a inside directory x

overwriting x/a shrinking keywords

% cat a

expand $Id$

do not process $Id:

xxx $

$Xinfo$

% kwexpand nonexistent

nonexistent:

% switch off expansion

% kwshrink with unknown file u

overwriting a shrinking keywords

overwriting x/a shrinking keywords

% cat

expand $Id$

do not process $Id:

xxx $

$Xinfo$

ignore $Id$

% hg cat