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 error___

    The description of the problem is not always clear (as in this case), but even when it is cryptic, it is almost always trivial to visually inspect the offending line in the style file and see what is wrong.

Uniquely Identifying ...

Get Mercurial: The Definitive Guide now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.