Help: templating

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"

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:

String. The unmodified author of the changeset.
String. The changeset bisection status.
List of strings. Any bookmarks associated with the changeset.
String. The name of the branch on which the changeset was committed.
List of strings. The children of the changeset.
String. The active bookmark, if it is associated with the changeset
Date information. The date when the changeset was committed.
String. The text of the changeset description.
String. Statistics of changes with the following format: "modified files: +added/-removed lines"
List of dicts with key, value entries of the 'extras' field of this changeset.
List of strings. Files added by this changeset.
List of strings. Files copied in this changeset with their sources.
List of strings. Like "file_copies" but displayed only if the --copied switch is set.
List of strings. Files removed by this changeset.
List of strings. Files modified by this changeset.
List of strings. All files modified, added, or removed by this changeset.
String. Most recent global tag in the ancestors of this changeset.
Integer. Longest path to the latest tag.
String. The changeset identification hash, as a 40 hexadecimal digit string.
String. The identification hash of the changeset's first parent, as a 40 digit hexadecimal string. If the changeset has no parents, all digits are 0.
Integer. The repository-local revision number of the changeset's first parent, or -1 if the changeset has no parents.
String. The identification hash of the changeset's second parent, as a 40 digit hexadecimal string. If the changeset has no second parent, all digits are 0.
Integer. The repository-local revision number of the changeset's second parent, or -1 if the changeset has no second parent.
List of strings. The parents of the changeset in "rev:node" format. If the changeset has only one "natural" parent (the predecessor revision) nothing is shown.
String. The changeset phase name.
Integer. The changeset phase index.
Integer. The repository-local changeset revision number.
List of strings. Updated subrepositories in the changeset.
List of strings. Any tags associated with the changeset.

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

List of filters:

Any text. Add an XHTML "<br />" tag before the end of every line except the last.
Date. Returns a human-readable date/time difference between the given date/time and the current date/time.
Any text. Treats the text as a path, and returns the last component of the path after splitting by the path separator (ignoring trailing separators). For example, "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "bar".
Date. Returns a date in a Unix date format, including the timezone: "Mon Sep 04 15:13:13 2006 0700".
Any text. Finds the first string that looks like an email address, and extracts just the domain component. Example: "User <>" becomes "".
Any text. Extracts the first string that looks like an email address. Example: "User <>" becomes "".
Any text. Returns the user portion of an email address.
Any text. Replaces the special XML/XHTML characters "&", "<" and ">" with XML entities, and filters out NUL characters.
Any text. Wraps the text to fit in 68 columns.
Any text. Wraps the text to fit in 76 columns.
Any text. Returns the first line of text.
Any text. Convert a binary Mercurial node identifier into its long hexadecimal representation.
Date. Returns the date as a pair of numbers: "1157407993 25200" (Unix timestamp, timezone offset).
Date. Returns the date in ISO 8601 format: "2009-08-18 13:00 +0200".
Date. Returns the date in ISO 8601 format, including seconds: "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
Date. Converts a date to local date.
Any text. Returns '(none)' if the string is empty.
Any text. Returns the input text rendered as a sequence of XML entities.
Any text. Returns the name before an email address, interpreting it as per RFC 5322.
Date. Returns a date using the Internet date format specified in RFC 3339: "2009-08-18T13:00:13+02:00".
Date. Returns a date using the same format used in email headers: "Tue, 18 Aug 2009 13:00:13 +0200".
Changeset hash. Returns the short form of a changeset hash, i.e. a 12 hexadecimal digit string.
Any text. Treats "text" as a bisection status, and returns a single-character representing the status (G: good, B: bad, S: skipped, U: untested, I: ignored). Returns single space if "text" is not a valid bisection status.
Date. Returns a date like "2006-09-18".
Any text. Split text into a list of lines.
Any type. Turns the value into text by converting values into text and concatenating them.
Any text. Strips all leading and trailing whitespace.
Treat the text as path and strip a directory level, if possible. For example, "foo" and "foo/bar" becomes "foo".
Any text. Returns the text, with every non-empty line except the first starting with a tab character.
Any text. Escapes all "special" characters. For example, "foo bar" becomes "foo%20bar".
Any text. Returns a short representation of a user name or email address.

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

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

  • date(date[, fmt])
  • fill(text[, width])
  • get(dict, key)
  • if(expr, then[, else])
  • ifcontains(expr, expr, then[, else])
  • ifeq(expr, expr, then[, else])
  • join(list, sep)
  • label(label, expr)
  • pad(text, width[, fillchar, right])
  • revset(query[, formatargs])
  • rstdoc(text, style)
  • shortest(node)
  • startswith(string, text)
  • strip(text[, chars])
  • sub(pat, repl, expr)
  • word(number, text[, separator])

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

  • expr % "{template}"

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"
  • 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"
  • 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 current bookmark with '*':
    $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, current, \"*\")} '}\n"
  • Mark the working copy parent with '@':
    $ hg log --template "{ifcontains(rev, revset('.'), '@')}\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"