Template Usage

Template Usage#

Mercurial allows you to customize output of commands through templates. You can either pass in a template or select an existing template-style from the command line, via the –template option.

You can customize output for any “log-like” command: log, outgoing, incoming, tip, parents, and heads.

Some built-in styles are packaged with Mercurial. These can be listed with `hg log –template list`. Example usage:

$ hg log -r1.0::1.1 --template changelog

A template is a piece of text, with markup to invoke variable expansion:

$ hg log -r1 --template "{node}\n"
b56ce7b07c52de7d5fd79fb89701ea538af65746

Keywords#

Strings in curly braces are called keywords. The availability of keywords depends on the exact context of the templater. These keywords are usually available for templating a log-like command:

The “date” keyword does not produce human-readable output. If you want to use a date in your output, you can use a filter to process it. Filters are functions which return a string based on the input variable. Be sure to use the stringify filter first when you’re applying a string-input filter to a list-like input variable. You can also use a chain of filters to get the desired output:

$ hg tip --template "{date|isodate}\n"
2008-08-21 18:22 +0000

Filters#

List of filters:

Note that a filter is nothing more than a function call, i.e. expr|filter is equivalent to filter(expr).

Functions#

In addition to filters, there are some basic built-in functions:

Operators#

We provide a limited set of infix arithmetic operations on integers:

+ for addition
- for subtraction
* for multiplication
/ for floor division (division rounded to integer nearest -infinity)

Division fulfills the law x = x / y + mod(x, y).

Also, for any expression that returns a list, there is a list operator:

expr % "{template}"

As seen in the above example, {template} is interpreted as a template. To prevent it from being interpreted, you can use an escape character \{ or a raw string prefix, r'...'.

The dot operator can be used as a shorthand for accessing a sub item:

  • expr.member is roughly equivalent to expr % '{member}' if expr returns a non-list/dict. The returned value is not stringified.

  • dict.key is identical to get(dict, 'key').

Aliases#

New keywords and functions can be defined in the templatealias section of a Mercurial configuration file:

<alias> = <definition>

Arguments of the form a1, a2, etc. are substituted from the alias into the definition.

For example,

[templatealias]
r = rev
rn = "{r}:{node|short}"
leftpad(s, w) = pad(s, w, ' ', True)

defines two symbol aliases, r and rn, and a function alias leftpad().

It’s also possible to specify complete template strings, using the templates section. The syntax used is the general template string syntax.

For example,

[templates]
nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"

defines a template, nodedate, which can be called like:

$ hg log -r . -Tnodedate

A template defined in templates section can also be referenced from another template:

$ hg log -r . -T "{rev} {nodedate}"

but be aware that the keywords cannot be overridden by templates. For example, a template defined as templates.rev cannot be referenced as {rev}.

A template defined in templates section may have sub templates which are inserted before/after/between items:

[templates]
myjson = ' {dict(rev, node|short)|json}'
myjson:docheader = '\{\n'
myjson:docfooter = '\n}\n'
myjson:separator = ',\n'

Examples#

Some sample command line templates:

  • Format lists, e.g. files:

    $ hg log -r 0 --template "files:\n{files % '  {file}\n'}"

  • Join the list of files with a “, “:

    $ hg log -r 0 --template "files: {join(files, ', ')}\n"

  • Join the list of files ending with “.py” with a “, “:

    $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"

  • Separate non-empty arguments by a “ “:

    $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"

  • Modify each line of a commit description:

    $ hg log --template "{splitlines(desc) % '**** {line}\n'}"

  • Format date:

    $ hg log -r 0 --template "{date(date, '%Y')}\n"

  • Display date in UTC:

    $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"

  • Output the description set to a fill-width of 30:

    $ hg log -r 0 --template "{fill(desc, 30)}"

  • Use a conditional to test for the default branch:

    $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
'on branch {branch}')}\n"

  • Append a newline if not empty:

    $ hg tip --template "{if(author, '{author}\n')}"

  • Label the output for use with the color extension:

    $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"

  • Invert the firstline filter, i.e. everything but the first line:

    $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"

  • Display the contents of the ‘extra’ field, one per line:

    $ hg log -r 0 --template "{join(extras, '\n')}\n"

  • Mark the active bookmark with ‘*’:

    $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"

  • Find the previous release candidate tag, the distance and changes since the tag:

    $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"

  • Mark the working copy parent with ‘@’:

    $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"

  • Show details of parent revisions:

    $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"

  • Show only commit descriptions that start with “template”:

    $ hg log --template "{startswith('template', firstline(desc))}\n"

  • Print the first word of each line of a commit message:

    $ hg log --template "{word(0, desc)}\n"