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
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:
:activebookmark: String. The active bookmark, if it is
associated with the changeset
:author: String. The unmodified author of the changeset.
:bisect: String. The changeset bisection status.
:bookmarks: List of strings. Any bookmarks associated with the
changeset. Also sets 'active', the name of the active bookmark.
:branch: String. The name of the branch on which the changeset was
committed.
:changessincelatesttag: Integer. All ancestors not in the latest tag.
:children: List of strings. The children of the changeset.
:currentbookmark: String. The active bookmark, if it is
associated with the changeset (DEPRECATED)
: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"
:extras: List of dicts with key, value entries of the 'extras'
field of this changeset.
: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: List of strings. The global tags on the most recent globally
tagged ancestor 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.
:subrepos: List of strings. Updated subrepositories in the changeset.
: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".
:count: List or text. Returns the length as an integer.
: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.
:lower: Any text. Converts the text to lowercase.
: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.
:revescape: Any text. Escapes all "special" characters, except @.
Forward slashes are escaped twice to prevent web servers from prematurely
unescaping them. For example, "@foo bar/baz" becomes "@foo%20bar%252Fbaz".
: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".
:splitlines: Any text. Split text into a list of lines.
: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 non-empty line
except the first starting with a tab character.
:upper: Any text. Converts the text to uppercase.
: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]): Format a date. See :hg:`help dates` for formatting
strings.
:diff([includepattern [, excludepattern]]): Show a diff, optionally
specifying files to include or exclude.
:fill(text[, width[, initialident[, hangindent]]]): Fill many
paragraphs with optional indentation. See the "fill" filter.
:get(dict, key): Get an attribute/key from an object. Some keywords
are complex types. This function allows you to obtain the value of an
attribute on these type.
:if(expr, then[, else]): Conditionally execute based on the result of
an expression.
:ifcontains(search, thing, then[, else]): Conditionally execute based
on whether the item "search" is in "thing".
:ifeq(expr1, expr2, then[, else]): Conditionally execute based on
whether 2 items are equivalent.
:indent(text, indentchars[, firstline]): Indents all non-empty lines
with the characters given in the indentchars string. An optional
third parameter will override the indent for the first line only
if present.
:join(list, sep): Join items in a list with a delimiter.
:label(label, expr): Apply a label to generated content. Content with
a label applied can result in additional post-processing, such as
automatic colorization.
:pad(text, width[, fillchar=' '[, right=False]]): Pad text with a
fill character.
:revset(query[, formatargs...]): Execute a revision set query. See
:hg:`help revset`.
:rstdoc(text, style): Format ReStructuredText.
:shortest(node, minlength=4): Obtain the shortest representation of
a node.
:startswith(pattern, text): Returns the value from the "text" argument
if it begins with the content from the "pattern" argument.
:strip(text[, chars]): Strip characters from a string.
:sub(pattern, replacement, expression): Perform text substitution
using regular expressions.
:word(number, text[, separator]): Return the nth word from a string.
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'...'".
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 active bookmark with '*'::
$ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\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"