Mercurial: The Definitive Guide

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