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

list of commands:

 kwdemo     print [keywordmaps] configuration and an expansion example

 kwexpand   expand keywords in working directory

 kwfiles    print files currently configured for keyword expansion

 kwshrink   revert expanded keywords in working directory

use "hg -v help keyword" to show aliases and global options

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

% do not expand debug templates

ADD = empty{file_adds}

$ADD$

$ADD: empty $

% kwshrink should exit silently in empty/invalid repo

% cat

expand $Id$

do not process $Id:

xxx $

expand $Id$

do not process $Id:

xxx $

ignore $Id$

% default keyword expansion

% commit

adding a

adding b

adding sym

a

b

sym

overwriting a expanding keywords

% status

% identify

f782df5f9602

% cat

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

do not process $Id:

xxx $

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

do not process $Id:

xxx $

ignore $Id$

% hg cat

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

do not process $Id:

xxx $

ignore $Id$

a

% touch

% status

% update

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

% cat

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

do not process $Id:

xxx $

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

do not process $Id:

xxx $

ignore $Id$

% copy

% kwfiles added

a

c

% commit

c

 c: copy a:0045e12f6c5791aac80ca6cbfd97709a88307292

overwriting c expanding keywords

% cat a c

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

do not process $Id:

xxx $

expand $Id: c,v 0ba462c0f077 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 f782df5f9602 c

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

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

+expand $Id: c,v 0ba462c0f077 1970/01/01 00:00:01 user $

+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 f782df5f9602 1970/01/01 00:00:00 user $

do not process $Id:

xxx $

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

do not process $Id:

xxx $

ignore $Id$

% hg cat

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

do not process $Id:

xxx $

ignore $Id$

a

% interrupted commit

transaction abort!

rollback completed

abort: edit failed: false exited with status 1

% status

M a

? log

% commit

a

overwriting a expanding keywords

% status

% cat

expand $Id: a 0729690beff6 Thu, 01 Jan 1970 00:00:02 +0000 user $

do not process $Id:

xxx $

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

expand $Id: a 0729690beff6 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 0729690beff6 Thu, 01 Jan 1970 00:00:02 +0000 user $

do not process $Id:

xxx $

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

ignore $Id$

a

% remove

% status

% rollback

rolling back last transaction

% status

R a

% revert a

% cat a

expand $Id: a 0729690beff6 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 1 changesets with 3 changes to 3 files

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

% incoming

comparing with test-keyword/Test-a/../Test

searching for changes

changeset:   1:0729690beff6

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 in given files

x/a

 x/a: copy a:779c764182ce5d43e2b1eb66ce06d7b47bfe342e

overwriting x/a expanding keywords

% cat a

expand $Id: x/a f27c134d2d9b 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: No such file or directory

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

expand $Id$

do not process $Id:

xxx $

$Xinfo$

ignore $Id$

% hg cat

expand $Id: a 0729690beff6 Thu, 01 Jan 1970 00:00:02 +0000 user $

do not process $Id:

xxx $

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

ignore $Id$

a

% cat

expand $Id$

do not process $Id:

xxx $

$Xinfo$

expand $Id$

do not process $Id:

xxx $

$Xinfo$

ignore $Id$

% hg cat

expand $Id$

do not process $Id:

xxx $

$Xinfo$

ignore $Id$

a