• Choose a category
• All
• Classic-Fiction

* * *

Combining Filters

It is easy to combine filters to yield output in the form you would like. The following chain of filters tidies up a description, then makes sure that it fits cleanly into 68 columns, then indents it by a further 8 characters (at least on Unix-like systems, where a tab is conventionally 8 characters wide).

$ hg log -r1 --template 'description:\n\t{desc|strip|fill68|tabindent}\n'

description:

added line to end of <> file.

in addition, added a file with the helpful name (at least i hope

that some might consider it so) of goodbye.

Note the use of \t (a tab character) in the template to force the first line to be indented; this is necessary since tabindent indents all lines except the first.

Keep in mind that the order of filters in a chain is significant. The first filter is applied to the result of the keyword; the second to the result of the first filter; and so on. For example, using fill68|tabindent gives very different results from tabindent|fill68.

From Templates to Styles

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.

The Simplest of Style Files

Our simple style file contains just one line:

$ echo 'changeset = "rev: {rev}\n"' > rev

$ hg log -l1 --style ./rev

rev: 3

This tells Mercurial, “if you’re printing a changeset, use the text on the right as the template.”

Style File Syntax

The syntax rules for a style file are simple:

The file is processed one line at a time.

Leading and trailing whitespace is ignored.

Empty lines are skipped.

If a line starts with either of the characters # or ;, the entire line is treated as a comment, and skipped as if empty.

A line starts with a keyword. This must start with an alphabetic character or underscore, and can subsequently contain any alphanumeric character or underscore (in regexp notation, a keyword must match [A-Za-z_][A-Za-z0-9_]*).

The next element must be an = character, which can be preceded or followed by an arbitrary amount of whitespace.

If the rest of the line starts and ends with matching quote characters (either single or double quotes), it is treated as a template body.

If the rest of the line does not start with a quote character, it is treated as the name of a file; the contents of this file will be read and used as a template body.

Style Files by Example

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.

Identifying Mistakes in Style Files

If Mercurial encounters a problem in a style file you are working on, it prints a terse error message that, once you figure out what it means, is actually quite useful.

$ cat broken.style

changeset =

Notice that broken.style attempts to define a changeset keyword, but forgets to give any content for it. When instructed to use this style file, Mercurial promptly complains.

$ hg log -r1 --style broken.style

abort: broken.style:1: parse error

This error message looks intimidating, but it is not too hard to follow:

The first component is simply Mercurial’s way of saying “I am giving up”:___abort___: broken.style:1: parse error

Next comes the name of the style file that contains the error:abort: ___broken.style___:1: parse error

Following the filename is the line number where the error was encountered:abort: broken.style:___1___: parse error

Finally, a description of what went wrong:abort: broken.style:1: ___parse