Packaged with Mercurial are some output styles that you can use immediately. A style is simply a precanned template that someone wrote and installed somewhere that Mercurial can find.

Before we take a look at Mercurial’s bundled styles, let’s review its normal output.

$ hg log -r1
changeset:   1:59ae2fd35d8a
tag:         mytag
user:        Bryan O'Sullivan <[email protected]>
date:        Tue May 05 06:44:45 2009 +0000
summary:     added line to end of <<hello>> file.

This is somewhat informative, but it takes up a lot of space—five lines of output per changeset. The compact style reduces this to three lines, presented in a sparse manner.

$ hg log --style compact
3[tip]   4b984b80759d   2009-05-05 06:44 +0000   bos
  Added tag v0.1 for changeset cefd14841d41

2[v0.1]   cefd14841d41   2009-05-05 06:44 +0000   bos
  Added tag mytag for changeset 59ae2fd35d8a

1[mytag]   59ae2fd35d8a   2009-05-05 06:44 +0000   bos
  added line to end of <<hello>> file.

0   6ed500684dd0   2009-05-05 06:44 +0000   bos
  added hello

The changelog style hints at the expressive power of Mercurial’s templating engine. This style attempts to follow the GNU Project’s changelog guidelines.

$ hg log --style changelog
2009-05-05  Bryan O'Sullivan  <[email protected]>

	* .hgtags:
	Added tag v0.1 for changeset cefd14841d41
	[4b984b80759d] [tip]

	* .hgtags:
	Added tag mytag for changeset 59ae2fd35d8a
	[cefd14841d41] [v0.1]

	* goodbye, hello:
	added line to end of <<hello>> file.

	in addition, added a file with the helpful name (at least i hope
	that some might consider it so) of goodbye.
	[59ae2fd35d8a] [mytag]

	* hello:
	added hello
	[6ed500684dd0]

You will not be shocked to learn that Mercurial’s default output style is named default.

[ui]
style = compact

All of Mercurial’s “log-like” commands let you use styles and templates: hg incoming, hg log, hg outgoing, and hg tip.

As of this writing, these are the only commands that support styles and templates. Since these are the most important commands that need customizable output, there has been little pressure from the Mercurial user community to add style and template support to other commands.

At its simplest, a Mercurial template is a piece of text. Some of the text never changes, while other parts are expanded, or replaced with new text, when necessary.

Before we continue, let’s look again at a simple example of Mercurial’s normal output.

$ hg log -r1
changeset:   1:59ae2fd35d8a
tag:         mytag
user:        Bryan O'Sullivan <[email protected]>
date:        Tue May 05 06:44:45 2009 +0000
summary:     added line to end of <<hello>> file.

Now, let’s run the same command, but using a template to change its output.

$ hg log -r1 --template 'i saw a changeset
'
i saw a changeset

The example above illustrates the simplest possible template; it’s just a piece of static text, printed once for each changeset. The --template option to the hg log command tells Mercurial to use the given text as the template when printing each changeset.

Notice that the template string above ends with the text . This is an escape sequence, telling Mercurial to print a newline at the end of each template item. If you omit this newline, Mercurial will run each piece of output together. See Escape Sequences for more details.

A template that prints a fixed string of text all the time isn’t very useful; let’s try something a bit more complex.

$ hg log --template 'i saw a changeset: {desc}
'
i saw a changeset: Added tag v0.1 for changeset cefd14841d41
i saw a changeset: Added tag mytag for changeset 59ae2fd35d8a
i saw a changeset: added line to end of <<hello>> file.

in addition, added a file with the helpful name (at least i hope that some 
might consider it so) 
of goodbye. i saw a changeset: added hello

As you can see, the string {desc} in the template has been replaced in the output with the description of each changeset. Every time Mercurial finds text enclosed in curly braces ({ and }), it will try to replace the braces and text with the expansion of whatever is inside. To print a literal curly brace, you must escape it, as described in Escape Sequences.

You can start writing simple templates immediately using the keywords below:

A few simple experiments will show us what to expect when we use these keywords; you can see the results below.

$ hg log -r1 --template 'author: {author}
'
author: Bryan O'Sullivan <[email protected]>
$ hg log -r1 --template 'desc:
{desc}
'
desc:
added line to end of <<hello>> file.

in addition, added a file with the helpful name (at least i hope that some 
might consider it so) 
of goodbye.
$ hg log -r1 --template 'files: {files}
'
files: goodbye hello
$ hg log -r1 --template 'file_adds: {file_adds}
'
file_adds: goodbye
$ hg log -r1 --template 'file_dels: {file_dels}
'
file_dels: 
$ hg log -r1 --template 'node: {node}
'
node: 59ae2fd35d8a09c1532bf5ecd9035b4ac6db2cda
$ hg log -r1 --template 'parents: {parents}
'
parents: 
$ hg log -r1 --template 'rev: {rev}
'
rev: 1
$ hg log -r1 --template 'tags: {tags}
'
tags: mytag

As noted above, the date keyword does not produce human-readable output, so we must treat it specially. This involves using a filter; see Filtering Keywords to Change Their Results.

$ hg log -r1 --template 'date: {date}
'
date: 1241505885.00
$ hg log -r1 --template 'date: {date|isodate}
'
date: 2009-05-05 06:44 +0000

Mercurial’s templating engine recognizes the most commonly used escape sequences in strings. When it sees a backslash () character, it looks at the following character and substitutes the two characters with a single replacement, as described below:

As indicated above, if you want the expansion of a template to contain a literal , {, or { character, you must escape it.

Some of the results of template expansion are not immediately easy to use. Mercurial lets you specify an optional chain of filters to modify the result of expanding a keyword. You have already seen a common filter, isodate, in action above, to make a date readable.

Below is a list of the most commonly used filters that Mercurial supports. While some filters can be applied to any text, others can only be used in specific circumstances. The name of each filter is followed first by an indication of where it can be used, then a description of its effect.

$ hg log -r1 --template 'description:
	{desc|strip|fill68|tabindent}
'
description:
	added line to end of <<hello>> file.

	in addition, added a file with the helpful name (at least i hope
	that some might consider it so) of goodbye.

A command-line template provides a quick and simple way to format some output. Templates can become verbose, though, and it’s useful to be able to give a template a name. A style file is a template with a name, stored in a file.

More than that, using a style file unlocks the power of Mercurial’s templating engine in ways that are not possible using the command-line --template option.

$ echo 'changeset = "rev: {rev}
"' > rev
$ hg log -l1 --style ./rev
rev: 3

To illustrate how to write a style file, we will construct a few by example. Rather than provide a complete style file and walk through it, we’ll mirror the usual process of developing a style file by starting with something very simple, and walking through a series of successively more complete examples.

$ cat broken.style
changeset =

$ hg log -r1 --style broken.style
abort: broken.style:1: parse error

$ hg log -r0 --template '{node}'
c190a4d6b8ed776cf4103dd4ed9260cc3b79ba27

$ cat > multiline << EOF
> changeset = "Changed in {node|short}:
{files}"
> file = "  {file}
"
> EOF
$ hg log --style multiline
Changed in f55a274d193b:
  .bashrc
  .hgrc
  test.c

$ svn log -r9653
------------------------------------------------------------------------
r9653 | sean.hefty | 2006-09-27 14:39:55 -0700 (Wed, 27 Sep 2006) | 5 lines

On reporting a route error, also include the status for the error,
rather than indicating a status of 0 when an error has occurred.

Signed-off-by: Sean Hefty <[email protected]>

------------------------------------------------------------------------

$ cat svn.template
r{rev} | {author|user} | {date|isodate} ({date|rfc822date})

{desc|strip|fill76}

------------------------------------------------------------------------

$ cat svn.style
header = '-----------------------------------------------------------------------

'
changeset = svn.template