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.
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".
escape Any text. Replaces the special XML/XHTML characters "&", "<"
and ">" with XML entities.
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 text before an email address.
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 the user portion of an email address.