Diff for "KeywordExtension"

Keyword Extension

This extension is distributed with recent versions of Mercurial.

Author: [wiki:ChristianEbert Christian Ebert]

Download site: [http://www.blacktrash.org/hg/hgkeyword/ keyword extension repository] including backwards compatible branch (Mercurial 0.9.2)

Overview

This extension allows the expansion of RCS/CVS-like and user defined keys in text files tracked by Mercurial. Expansion takes place in the working directory or/and when creating a distribution using "hg archive".

Configuration

To enable this extension add it to the '[extensions]' stanza in the hgrc file:

[extensions]
hgext.keyword=
#or, if keyword.py is not in the hgext folder:
#keyword=/path/to/keyword.py

Additional configuration is done in the [keyword] and [keywordmaps] sections in your configuration file:

# filename patterns for expansion are configured in this section
[keyword]
# expand keywords in all python files in working dir
**.py =
# do not expand keywords in files matching "x*" in working dir
x* = ignore
...
# override the cvs-like default mappings with customized keyword = expansion pairs,
# where expansion values contain Mercurial templates and filters
[keywordmaps]
HGdate = {date|rfc822date}
lastlog = {desc}
checked in by = {author}

For speed and security reasons (avoidance of inadvertedly expanded keywords) it is recommended to enable the extension per repo only in repo/.hg/hgrc, not globally, and to fine tune the [keyword] filename patterns with great care.

Usage

The main functionality of the extension is done in background by automatically expanding the defined keys (or default ones), without user interaction. An additional template filter "utcdate" is provided to get %Y/%m/%d %H:%M:%S date format.

Keywords should appear in the source files as $keyword$ with no spaces, although $keyword:  $ (two spaces!) seems to work.

$keyword: $ (single space) does not work.

The extension provides the following convenience commands:

kwdemo, kwfiles

To get an idea what the extension actually does and/or to test your customizations (templates are rather sparsely documented), run "hg kwdemo".

Example output of "hg kwdemo --default":

        config using default keyword template maps
[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}

        default keywords expanded
$RCSFile: demo.txt,v $
$Author: blacktrash $
$Header: /tmp/kwdemo.Oz46E2/demo.txt,v 2ad3dcb8d811 2007/07/17 12:00:47 blacktrash $
$Source: /tmp/kwdemo.Oz46E2/demo.txt,v $
$Date: 2007/07/17 12:00:47 $
$Id: demo.txt,v 2ad3dcb8d811 2007/07/17 12:00:47 blacktrash $
$Revision: 2ad3dcb8d811 $

To crosscheck which files in your working directory are matched by the current [keyword] patterns, use "hg kwfiles".

kwshrink, kwexpand

Run "hg kwshrink" before changing or disabling currently active keywords.

Do not forget to "hg kwshrink" in the above cases! Otherwise the currently expanded keywords become part of change history.

Run "hg kwexpand" to force expansion in the working directory after enabling it, or after a keyword configuration change.

CategoryExtension