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

list of commands:

 kwdemo     print [keywordmaps] configuration and an expansion example

 kwexpand   expand keywords in the working directory

 kwfiles    show files configured for keyword expansion

 kwshrink   revert expanded keywords in the working directory

enabled extensions:

 keyword   expand keywords in tracked files

 mq        manage a stack of patches

 notify    hooks for sending email notifications at commit/push time

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 $

% 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

% interrupted commit should not change state or run commit hook

abort: empty commit message

% status

A a

A b

% commit

a

b

overwriting a expanding keywords

running hook commit.test: cp a hooktest

committed changeset 1:ef63ca68695bc9495032c6fda1350c71e6d256e9

% status

? hooktest

% identify

ef63ca68695b

% cat

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

do not process $Id:

xxx $

ignore $Id$

% hg cat

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

do not process $Id:

xxx $

ignore $Id$

a

% diff a hooktest

% removing commit hook from config

% bundle

2 changesets found

% notify on pull to check whether keywords stay as is in email

% ie. if patch.diff wrapper acts as it should

% 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

diff -r 000000000000 -r a2392c293916 sym

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

+++ b/sym	Sat Feb 09 20:25:47 2008 +0100

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

+a

\ No newline at end of file

diff -r a2392c293916 -r ef63ca68695b a

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

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

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

+expand $Id$

+do not process $Id:

+xxx $

diff -r a2392c293916 -r ef63ca68695b b

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

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

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

+ignore $Id$

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

% remove notify config

% touch

% status

% update

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

% cat

expand $Id: a,v ef63ca68695b 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 ef63ca68695b 1970/01/01 00:00:00 user $

do not process $Id:

xxx $

$Id: c,v 40a904bbbe4c 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 40a904bbbe4cd4ab0a1f28411e35db26341a40ad

# Parent  ef63ca68695bc9495032c6fda1350c71e6d256e9

cndiff

diff -r ef63ca68695b -r 40a904bbbe4c 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

% qgoto - should imply qpush

applying mqtest.diff

now at: mqtest.diff

% cat

$Id: c,v 40a904bbbe4c 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

committed changeset 2:e22d299ac0c2bd8897b3df5114374b9e4d4ca62f

% cat a c

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

do not process $Id:

xxx $

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

do not process $Id:

xxx $

% touch copied c

% status

% kwfiles

a

c

% diff --rev

diff -r ef63ca68695b 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, 0 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 ef63ca68695b 1970/01/01 00:00:00 user $

do not process $Id:

xxx $

ignore $Id$

% hg cat

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

do not process $Id:

xxx $

ignore $Id$

a

% interrupted commit should not change state

abort: empty commit message

% status

M a

? c

? log

% commit

a

overwriting a expanding keywords

committed changeset 2:bb948857c743469b22bbf51f7ec8112279ca5d83

% status

? c

% verify

checking changesets

checking manifests

crosschecking files in changesets and manifests

checking files

3 files, 3 changesets, 4 total revisions

% cat

expand $Id: a bb948857c743 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 bb948857c743 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

committed changeset 3:d14c712653769de926994cf7fbb06c8fbd68f012

% status

? c