Help: templating
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.
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.
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.
