Template Usage

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

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

Four styles are packaged with Mercurial: default (the style used when no explicit preference is passed), compact, changelog, and xml. Usage:

$ hg log -r1 --style changelog

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

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

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:

author: String. The unmodified author of the changeset.
bisect: String. The changeset bisection status.
bookmarks: List of strings. Any bookmarks associated with the changeset.
branch: String. The name of the branch on which the changeset was committed.
branches: List of strings. The name of the branch on which the changeset was committed. Will be empty if the branch name was default.
children: List of strings. The children of the changeset.
date: Date information. The date when the changeset was committed.
desc: String. The text of the changeset description.
diffstat: String. Statistics of changes with the following format: "modified files: +added/-removed lines"
file_adds: List of strings. Files added by this changeset.
file_copies: List of strings. Files copied in this changeset with their sources.
file_copies_switch: List of strings. Like "file_copies" but displayed only if the --copied switch is set.
file_dels: List of strings. Files removed by this changeset.
file_mods: List of strings. Files modified by this changeset.
files: List of strings. All files modified, added, or removed by this changeset.
latesttag: String. Most recent global tag in the ancestors of this changeset.
latesttagdistance: Integer. Longest path to the latest tag.
node: String. The changeset identification hash, as a 40 hexadecimal digit string.
p1node: 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.
p1rev: Integer. The repository-local revision number of the changeset's first parent, or -1 if the changeset has no parents.
p2node: 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.
p2rev: Integer. The repository-local revision number of the changeset's second parent, or -1 if the changeset has no second parent.
parents: 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.
phase: String. The changeset phase name.
phaseidx: Integer. The changeset phase index.
rev: Integer. The repository-local changeset revision number.
tags: 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:

addbreaks: Any text. Add an XHTML "<br />" tag before the end of every line except the last.
age: Date. Returns a human-readable date/time difference between the given date/time and the current date/time.
basename: 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: Date. Returns a date in a Unix date format, including the timezone: "Mon Sep 04 15:13:13 2006 0700".
domain: Any text. Finds the first string that looks like an email address, and extracts just the domain component. Example: "User <user@example.com>" becomes "example.com".
email: Any text. Extracts the first string that looks like an email address. Example: "User <user@example.com>" becomes "user@example.com".
emailuser: Any text. Returns the user portion of an email address.
escape: Any text. Replaces the special XML/XHTML characters "&", "<" and ">" with XML entities, and filters out NUL characters.
fill68: Any text. Wraps the text to fit in 68 columns.
fill76: Any text. Wraps the text to fit in 76 columns.
firstline: Any text. Returns the first line of text.
hex: Any text. Convert a binary Mercurial node identifier into its long hexadecimal representation.
hgdate: Date. Returns the date as a pair of numbers: "1157407993 25200" (Unix timestamp, timezone offset).
isodate: Date. Returns the date in ISO 8601 format: "2009-08-18 13:00 +0200".
isodatesec: Date. Returns the date in ISO 8601 format, including seconds: "2009-08-18 13:00:13 +0200". See also the rfc3339date filter.
localdate: Date. Converts a date to local date.
nonempty: Any text. Returns '(none)' if the string is empty.
obfuscate: Any text. Returns the input text rendered as a sequence of XML entities.
person: Any text. Returns the name before an email address, interpreting it as per RFC 5322.
rfc3339date: Date. Returns a date using the Internet date format specified in RFC 3339: "2009-08-18T13:00:13+02:00".
rfc822date: Date. Returns a date using the same format used in email headers: "Tue, 18 Aug 2009 13:00:13 +0200".
short: Changeset hash. Returns the short form of a changeset hash, i.e. a 12 hexadecimal digit string.
shortbisect: 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.
shortdate: Date. Returns a date like "2006-09-18".
stringify: Any type. Turns the value into text by converting values into text and concatenating them.
strip: Any text. Strips all leading and trailing whitespace.
stripdir: Treat the text as path and strip a directory level, if possible. For example, "foo" and "foo/bar" becomes "foo".
tabindent: Any text. Returns the text, with every line except the first starting with a tab character.
urlescape: Any text. Escapes all "special" characters. For example, "foo bar" becomes "foo%20bar".
user: 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])
ifeq(expr, expr, then[, else])
join(list, sep)
label(label, expr)
sub(pat, repl, expr)
rstdoc(text, style)

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"

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"
```