Help: templating

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

Keywords

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.
branches: List of strings. The name of the branch on which the changeset was committed. Will be empty if the branch name was default. (DEPRECATED)
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"
envvars: A dictionary of environment variables. (EXPERIMENTAL)
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.
graphnode: String. The character representing the changeset node in an ASCII revision graph
index: Integer. The current iteration of the loop. (0 indexed)
latesttag: List of strings. The global tags on the most recent globally tagged ancestor of this changeset. If no such tags exist, the list consists of the single string "null".
latesttagdistance: Integer. Longest path to the latest tag.
namespaces: Dict of lists. Names attached to this changeset per namespace.
node: String. The changeset identification hash, as a 40 hexadecimal digit string.
obsolete: String. Whether the changeset is obsolete.
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.
peerpaths: A dictionary of repository locations defined in the [paths] section of your configuration file. (EXPERIMENTAL)
phase: String. The changeset phase name.
phaseidx: Integer. The changeset phase index.
predecessors: Returns the list if the closest visible successors
rev: Integer. The repository-local changeset revision number.
subrepos: List of strings. Updated subrepositories in the changeset.
successorssets: Returns a string of sets of successors for a changectx
Format used is: [ctx1, ctx2], [ctx3] if ctx has been splitted into ctx1 and ctx2 while also diverged into ctx3
tags: List of strings. Any tags associated with the changeset.
termwidth: Integer. The width of the current terminal.
troubles: List of strings. Evolution troubles affecting the changeset.
(EXPERIMENTAL)

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

Filters

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.
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.
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.
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.
utf8: Any text. Converts from the local character encoding to UTF-8.

Note that a filter is nothing more than a function call, i.e. "expr|filter" is equivalent to "filter(expr)".

Functions

In addition to filters, there are some basic built-in functions:

date(date[, fmt]): Format a date. See 'hg help dates' for formatting strings. The default is a Unix date format, including the timezone: "Mon Sep 04 15:13:13 2006 0700".
dict([[key=]value...]): Construct a dict from key-value pairs. A key may be omitted if a value expression can provide an unambiguous name.
diff([includepattern [, excludepattern]]): Show a diff, optionally specifying files to include or exclude.
files(pattern): All files of the current changeset matching the pattern. See 'hg help patterns'.
fill(text[, width[, initialident[, hangindent]]]): Fill many paragraphs with optional indentation. See the "fill" filter.
formatnode(node): Obtain the preferred form of a changeset hash. (DEPRECATED)
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 types.
if(expr, then[, else]): Conditionally execute based on the result of an expression.
ifcontains(needle, haystack, then[, else]): Conditionally execute based on whether the item "needle" is in "haystack".
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.
latesttag([pattern]): The global tags matching the given pattern on the most recent globally tagged ancestor of this changeset. If no such tags exist, the "{tag}" template resolves to the string "null".
localdate(date[, tz]): Converts a date to the specified timezone. The default is local date.
mod(a, b): Calculate a mod b such that a / b + a mod b == a
pad(text, width[, fillchar=' '[, left=False]]): Pad text with a fill character.
relpath(path): Convert a repository-absolute path into a filesystem path relative to the current working directory.
revset(query[, formatargs...]): Execute a revision set query. See 'hg help revset'.
rstdoc(text, style): Format reStructuredText.
separate(sep, args): Add a separator between non-empty arguments.
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. By default, strips all leading and trailing whitespace.
sub(pattern, replacement, expression): Perform text substitution using regular expressions.
word(number, text[, separator]): Return the nth word from a string.

Operators

We provide a limited set of infix arithmetic operations on integers:

+ for addition
- for subtraction
* for multiplication
/ for floor division (division rounded to integer nearest -infinity)

Division fulfills the law x = x / y + mod(x, y).

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'...'".

Aliases

New keywords and functions can be defined in the "templatealias" section of a Mercurial configuration file:

<alias> = <definition>

Arguments of the form 'a1', 'a2', etc. are substituted from the alias into the definition.

For example,

[templatealias]
r = rev
rn = "{r}:{node|short}"
leftpad(s, w) = pad(s, w, ' ', True)

defines two symbol aliases, "r" and "rn", and a function alias "leftpad()".

It's also possible to specify complete template strings, using the "templates" section. The syntax used is the general template string syntax.

For example,

[templates]
nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"

defines a template, "nodedate", which can be called like:

$ hg log -r . -Tnodedate

A template defined in "templates" section can also be referenced from another template:

$ hg log -r . -T "{rev} {nodedate}"

but be aware that the keywords cannot be overridden by templates. For example, a template defined as "templates.rev" cannot be referenced as "{rev}".

A template defined in "templates" section may have sub templates which are inserted before/after/between items:

[templates]
myjson = ' {dict(rev, node|short)|json}'
myjson:docheader = '\{\n'
myjson:docfooter = '\n}\n'
myjson:separator = ',\n'

Examples

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"

Join the list of files ending with ".py" with a ", ":

$ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"

Separate non-empty arguments by a " ":

$ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\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"

Display date in UTC:

$ hg log -r 0 --template "{localdate(date, 'UTC')|date}\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"

Find the previous release candidate tag, the distance and changes since the tag:

$ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"

Mark the working copy parent with '@':

$ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"

Show details of parent revisions:

$ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\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"
```

Mercurial > might-and-magic-trilogy