|
Size: 3240
Comment: explain kwdemo, kwshrink, kwexpand commands
|
← Revision 51 as of 2024-03-06 12:11:11 ⇥
Size: 4619
Comment: way backwards compatible repo not hosted anymore
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| == Keyword Expansion extension == '''This extension is not being distributed along with Mercurial.''' |
#format wiki #language en ## page was renamed from KeywordExpansionExtension == Keyword Extension == <!> This is considered a [[FeaturesOfLastResort|feature of last resort]]. |
| Line 4: | Line 7: |
| ''Author: Christian Ebert'' | '''This extension is distributed with Mercurial.''' |
| Line 6: | Line 9: |
| Download site: [http://www.blacktrash.org/hg/hgkeyword/ keyword expansion repository]. Mirror of crew repo plus keyword extension: [http://www.blacktrash.org/hg/hg-crew-keyword/ Mercurial crew + keyword]. |
''Author: [[ChristianEbert|Christian Ebert]]'' |
| Line 11: | Line 12: |
| 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". | |
| Line 12: | Line 14: |
| 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". |
Keywords expand to the changeset data pertaining to the latest change relative to the working directory parent of each file. <!> If you just want to version your ''entire repo'', do not use this extension but let your build system take care of it. Something along the lines of {{{ hg -q id > version }}} before distribution might be well enough if '''file-wise''' keyword expansion in the source is not absolutely required. See also: VersioningWithMake. |
| Line 20: | Line 28: |
| hgext.keyword= | keyword= |
| Line 24: | Line 32: |
| Additional configuration is done in the [keyword] and [keywordmaps] sections in your configuration file: | |
| Line 25: | Line 34: |
| Additional configuration is done in the [keyword] and [keywordmaps] sections in your configuration file: | |
| Line 34: | Line 42: |
| # in case you prefer your own keyword maps over the cvs-like defaults: # using "key-to-be-expanded = value" lines, where values are taken from the available Mercurial template names. # an additional filter "utcdate" is provided to get "%Y/%m/%d %H:%M:%S" date format. |
# override the cvs-like default mappings with customized keyword = expansion pairs, # where expansion values contain Mercurial templates and filters |
| Line 39: | Line 46: |
| lastlog = {desc} ## same as {desc|firstline} in this context | lastlog = {desc} |
| Line 42: | Line 49: |
| <!> For speed and security reasons (avoidance of inadvertently 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. | |
| Line 44: | Line 52: |
| The main functionality of the extension is done in background by automatically expanding the defined keys (or default ones), without user interaction. | 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. |
| Line 46: | Line 54: |
| However, the extension provides the following convenience commands: | Before expansion keywords should appear in the source files delimited by {{{$}}} signs: |
| Line 48: | Line 56: |
| ==== kwdemo ==== | {{{ This is a $Keyword$ awaiting expansion. }}} As keywords are freely configurable, take care that they differ from potential {{{$}}}-delimited patterns in the actual source to avoid accidental expansion. The extension provides the following convenience commands: ==== kwdemo, kwfiles ==== |
| Line 51: | Line 66: |
| Example output of "hg kwdemo --default": | Example output of "hg kwdemo --default"<<FootNote({{{RCSFile}}} is incorrect, but kept for backwards compatibility with previous versions of the extension.)>>: |
| Line 54: | Line 69: |
| config with default keyword template maps: | configuration using default keyword template maps [extensions] keyword = |
| Line 58: | Line 75: |
| Author = {author|user} Date = {date|utcdate} Header = {root}/{file},v {node|short} {date|utcdate} {author|user} Id = {file|basename},v {node|short} {date|utcdate} {author|user} |
|
| Line 59: | Line 80: |
| Author = {author|user} Header = {root}/{file},v {node|short} {date|utcdate} {author|user} |
RCSfile = {file|basename},v Revision = {node|short} |
| Line 62: | Line 83: |
| Date = {date|utcdate} Id = {file|basename},v {node|short} {date|utcdate} {author|user} Revision = {node|short} |
|
| Line 66: | Line 84: |
| default keywords expanded: | keywords expanded $Author: blacktrash $ $Date: 2007/07/17 12:00:47 $ $Header: /tmp/kwdemo.Oz46E2/demo.txt,v 2ad3dcb8d811 2007/07/17 12:00:47 blacktrash $ $Id: demo.txt,v 2ad3dcb8d811 2007/07/17 12:00:47 blacktrash $ |
| Line 68: | Line 90: |
| $Author: blacktrash $ $Header: /tmp/kwdemo.Oz46E2/demo.txt,v 2ad3dcb8d811 2007/07/17 12:00:47 blacktrash $ |
$RCSfile: demo.txt,v $ $Revision: 2ad3dcb8d811 $ |
| Line 71: | Line 93: |
| $Date: 2007/07/17 12:00:47 $ $Id: demo.txt,v 2ad3dcb8d811 2007/07/17 12:00:47 blacktrash $ $Revision: 2ad3dcb8d811 $ |
|
| Line 75: | Line 94: |
| To crosscheck which files in your working directory are matched by the current {{{[keyword]}}} patterns, use "hg kwfiles". | |
| Line 77: | Line 97: |
| Run "hg kwshrink" before eg. changing the currently active keywords, if you don't want the expanded keywords stored in the change history. | Run "hg kwshrink" before changing or disabling currently active keywords. |
| Line 79: | Line 99: |
| Expanding keywords only in the current working copy allows you to share changes with other repos that do not have the same or no keyword setup. This can sometimes cause a problem with "hg import" if the change context contains an active keyword. To overcome this run "hg kwshrink", (re)import, "hg kwexpand". Or, better, use bundle/unbundle to share changes. | <!> 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. ==== Features request ==== * Custom template filters for keyword expansion... I would like to allow $License$ style expansion to add automatic formatted license preamble to sources files managed by Mercurial and this seems like the perfect extension for this purpose. -- EtienneRobillard <<DateTime(2011-04-27T12:54:31Z)>> |
| Line 82: | Line 107: |
| CategoryExtension | CategoryBundledExtension |
Keyword Extension
This is considered a feature of last resort.
This extension is distributed with Mercurial.
Author: Christian Ebert
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".
Keywords expand to the changeset data pertaining to the latest change relative to the working directory parent of each file.
If you just want to version your entire repo, do not use this extension but let your build system take care of it. Something along the lines of
hg -q id > version
before distribution might be well enough if file-wise keyword expansion in the source is not absolutely required. See also: VersioningWithMake.
Configuration
To enable this extension add it to the '[extensions]' stanza in the hgrc file:
[extensions] 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 inadvertently 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.
Before expansion keywords should appear in the source files delimited by $ signs:
This is a $Keyword$ awaiting expansion.
As keywords are freely configurable, take care that they differ from potential $-delimited patterns in the actual source to avoid accidental expansion.
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"1:
configuration using default keyword template maps
[extensions]
keyword =
[keyword]
demo.txt =
[keywordmaps]
Author = {author|user}
Date = {date|utcdate}
Header = {root}/{file},v {node|short} {date|utcdate} {author|user}
Id = {file|basename},v {node|short} {date|utcdate} {author|user}
RCSFile = {file|basename},v
RCSfile = {file|basename},v
Revision = {node|short}
Source = {root}/{file},v
keywords expanded
$Author: blacktrash $
$Date: 2007/07/17 12:00:47 $
$Header: /tmp/kwdemo.Oz46E2/demo.txt,v 2ad3dcb8d811 2007/07/17 12:00:47 blacktrash $
$Id: demo.txt,v 2ad3dcb8d811 2007/07/17 12:00:47 blacktrash $
$RCSFile: demo.txt,v $
$RCSfile: demo.txt,v $
$Revision: 2ad3dcb8d811 $
$Source: /tmp/kwdemo.Oz46E2/demo.txt,v $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.
Features request
Custom template filters for keyword expansion... I would like to allow $License$ style expansion to add automatic formatted license preamble to sources files managed by Mercurial and this seems like the perfect extension for this purpose. -- EtienneRobillard 2011-04-27 12:54:31
RCSFile is incorrect, but kept for backwards compatibility with previous versions of the extension. (1)