# keyword

Contents

- Description
- Commands
  - Uncategorized commands

expand keywords in tracked files

# Description

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.

Keywords expand to the changeset data pertaining to the latest change relative to the working directory parent of each file.

Configuration is done in the [keyword], [keywordset] and [keywordmaps] sections of hgrc files.

Example:

    [keyword]
    # expand keywords in every python file except those matching "x*"
    **.py =
    x*    = ignore

    [keywordset]
    # prefer svn- over cvs-like default keywordmaps
    svn = True

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`. See `hg help templates` for a list of available templates and filters.

Three additional date template filters are provided:

`utcdate`: | "2006/09/18 15:13:13"
`svnutcdate`: | "2006-09-18 15:13:13Z"
`svnisodate`: | "2006-09-18 08:13:13 -700 (Mon, 18 Sep 2006)"

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 configuration changes.

Before changing/disabling active keywords, you must run `hg kwshrink` to avoid 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.

# Commands

## Uncategorized commands

### kwdemo

print [keywordmaps] configuration and an expansion example:

    hg kwdemo [-d] [-f RCFILE] [TEMPLATEMAP]...

Show current, custom, or default keyword template maps and their expansions.

Extend the current configuration by specifying maps as arguments and using -f/--rcfile to source an external hgrc file.

Use -d/--default to disable current configuration.

See `hg help templates` for information on templates and filters.

Options:

`-d, --default` | show default keyword template maps
`-f, --rcfile <FILE>`
| read maps from rcfile

### kwexpand

expand keywords in the working directory:

    hg kwexpand [OPTION]... [FILE]...

Run after (re)enabling keyword expansion.

kwexpand refuses to run if given files contain local changes.

Options:

`-I, --include <PATTERN[+]>`
| include names matching the given patterns
`-X, --exclude <PATTERN[+]>`
| exclude names matching the given patterns

[+] marked option can be specified multiple times

### kwfiles

show files configured for keyword expansion:

    hg kwfiles [OPTION]... [FILE]...

List which files in the working directory are matched by the [keyword] configuration patterns.

Useful to prevent inadvertent keyword expansion and to speed up execution by including only files that are actual candidates for expansion.

See `hg help keyword` on how to construct patterns both for inclusion and exclusion of files.

With -A/--all and -v/--verbose the codes used to show the status of files are:

    K = keyword expansion candidate
    k = keyword expansion candidate (not tracked)
    I = ignored
    i = ignored (not tracked)

Options:

`-A, --all` | show keyword status flags of all files
`-i, --ignore` | show files excluded from expansion
`-u, --unknown` | only show unknown (not tracked) files
`-I, --include <PATTERN[+]>`
| include names matching the given patterns
`-X, --exclude <PATTERN[+]>`
| exclude names matching the given patterns

[+] marked option can be specified multiple times

### kwshrink

revert expanded keywords in the working directory:

    hg kwshrink [OPTION]... [FILE]...

Must be run before changing/disabling active keywords.

kwshrink refuses to run if given files contain local changes.

Options:

`-I, --include <PATTERN[+]>`
| include names matching the given patterns
`-X, --exclude <PATTERN[+]>`
| exclude names matching the given patterns

[+] marked option can be specified multiple times