Mercurial Mercurial > kg / help
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | help
 

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.
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"
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
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.
namespaces
Dict of lists. Names attached to this changeset per namespace.
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.
termwidth
Integer. The width of the current terminal.

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

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

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

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

Some sample command line templates:

kg