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.
Five styles are packaged with Mercurial: default (the style used
when no explicit preference is passed), compact, changelog,
phases 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"
