igor@402: \chapter{Customising the output of Mercurial}
igor@402: \label{chap:template}
igor@402:
igor@402: Mercurial provides a powerful mechanism to let you control how it
igor@402: displays information. The mechanism is based on templates. You can
igor@402: use templates to generate specific output for a single command, or to
igor@402: customise the entire appearance of the built-in web interface.
igor@402:
igor@402: \section{Using precanned output styles}
igor@402: \label{sec:style}
igor@402:
igor@402: Packaged with Mercurial are some output styles that you can use
igor@402: immediately. A style is simply a precanned template that someone
igor@402: wrote and installed somewhere that Mercurial can find.
igor@402:
igor@402: Before we take a look at Mercurial's bundled styles, let's review its
igor@402: normal output.
igor@402:
igor@402: \interaction{template.simple.normal}
igor@402:
igor@402: This is somewhat informative, but it takes up a lot of space---five
igor@402: lines of output per changeset. The \texttt{compact} style reduces
igor@402: this to three lines, presented in a sparse manner.
igor@402:
igor@402: \interaction{template.simple.compact}
igor@402:
igor@402: The \texttt{changelog} style hints at the expressive power of
igor@402: Mercurial's templating engine. This style attempts to follow the GNU
igor@402: Project's changelog guidelines\cite{web:changelog}.
igor@402:
igor@402: \interaction{template.simple.changelog}
igor@402:
igor@402: You will not be shocked to learn that Mercurial's default output style
igor@402: is named \texttt{default}.
igor@402:
igor@402: \subsection{Setting a default style}
igor@402:
igor@402: You can modify the output style that Mercurial will use for every
igor@402: command by editing your \hgrc\ file, naming the style you would
igor@402: prefer to use.
igor@402:
igor@402: \begin{codesample2}
igor@402: [ui]
igor@402: style = compact
igor@402: \end{codesample2}
igor@402:
igor@402: If you write a style of your own, you can use it by either providing
igor@402: the path to your style file, or copying your style file into a
igor@402: location where Mercurial can find it (typically the \texttt{templates}
igor@402: subdirectory of your Mercurial install directory).
igor@402:
igor@402: \section{Commands that support styles and templates}
igor@402:
igor@402: All of Mercurial's ``\texttt{log}-like'' commands let you use styles
igor@402: and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and
igor@402: \hgcmd{tip}.
igor@402:
igor@402: As I write this manual, these are so far the only commands that
igor@402: support styles and templates. Since these are the most important
igor@402: commands that need customisable output, there has been little pressure
igor@402: from the Mercurial user community to add style and template support to
igor@402: other commands.
igor@402:
igor@402: \section{The basics of templating}
igor@402:
igor@402: At its simplest, a Mercurial template is a piece of text. Some of the
igor@402: text never changes, while other parts are \emph{expanded}, or replaced
igor@402: with new text, when necessary.
igor@402:
igor@402: Before we continue, let's look again at a simple example of
igor@402: Mercurial's normal output.
igor@402:
igor@402: \interaction{template.simple.normal}
igor@402:
igor@402: Now, let's run the same command, but using a template to change its
igor@402: output.
igor@402:
igor@402: \interaction{template.simple.simplest}
igor@402:
igor@402: The example above illustrates the simplest possible template; it's
igor@402: just a piece of static text, printed once for each changeset. The
igor@402: \hgopt{log}{--template} option to the \hgcmd{log} command tells
igor@402: Mercurial to use the given text as the template when printing each
igor@402: changeset.
igor@402:
igor@402: Notice that the template string above ends with the text
igor@402: ``\Verb+\n+''. This is an \emph{escape sequence}, telling Mercurial
igor@402: to print a newline at the end of each template item. If you omit this
igor@402: newline, Mercurial will run each piece of output together. See
igor@402: section~\ref{sec:template:escape} for more details of escape sequences.
igor@402:
igor@402: A template that prints a fixed string of text all the time isn't very
igor@402: useful; let's try something a bit more complex.
igor@402:
igor@402: \interaction{template.simple.simplesub}
igor@402:
igor@402: As you can see, the string ``\Verb+{desc}+'' in the template has been
igor@402: replaced in the output with the description of each changeset. Every
igor@402: time Mercurial finds text enclosed in curly braces (``\texttt{\{}''
igor@402: and ``\texttt{\}}''), it will try to replace the braces and text with
igor@402: the expansion of whatever is inside. To print a literal curly brace,
igor@402: you must escape it, as described in section~\ref{sec:template:escape}.
igor@402:
igor@402: \section{Common template keywords}
igor@402: \label{sec:template:keyword}
igor@402:
igor@402: You can start writing simple templates immediately using the keywords
igor@402: below.
igor@402:
igor@402: \begin{itemize}
igor@402: \item[\tplkword{author}] String. The unmodified author of the changeset.
igor@402: \item[\tplkword{branches}] String. The name of the branch on which
igor@402: the changeset was committed. Will be empty if the branch name was
igor@402: \texttt{default}.
igor@402: \item[\tplkword{date}] Date information. The date when the changeset
igor@402: was committed. This is \emph{not} human-readable; you must pass it
igor@402: through a filter that will render it appropriately. See
igor@402: section~\ref{sec:template:filter} for more information on filters.
igor@402: The date is expressed as a pair of numbers. The first number is a
igor@402: Unix UTC timestamp (seconds since January 1, 1970); the second is
igor@402: the offset of the committer's timezone from UTC, in seconds.
igor@402: \item[\tplkword{desc}] String. The text of the changeset description.
igor@402: \item[\tplkword{files}] List of strings. All files modified, added, or
igor@402: removed by this changeset.
igor@402: \item[\tplkword{file\_adds}] List of strings. Files added by this
igor@402: changeset.
igor@402: \item[\tplkword{file\_dels}] List of strings. Files removed by this
igor@402: changeset.
igor@402: \item[\tplkword{node}] String. The changeset identification hash, as a
igor@402: 40-character hexadecimal string.
igor@402: \item[\tplkword{parents}] List of strings. The parents of the
igor@402: changeset.
igor@402: \item[\tplkword{rev}] Integer. The repository-local changeset revision
igor@402: number.
igor@402: \item[\tplkword{tags}] List of strings. Any tags associated with the
igor@402: changeset.
igor@402: \end{itemize}
igor@402:
igor@402: A few simple experiments will show us what to expect when we use these
igor@402: keywords; you can see the results in
igor@402: figure~\ref{fig:template:keywords}.
igor@402:
igor@402: \begin{figure}
igor@402: \interaction{template.simple.keywords}
igor@402: \caption{Template keywords in use}
igor@402: \label{fig:template:keywords}
igor@402: \end{figure}
igor@402:
igor@402: As we noted above, the date keyword does not produce human-readable
igor@402: output, so we must treat it specially. This involves using a
igor@402: \emph{filter}, about which more in section~\ref{sec:template:filter}.
igor@402:
igor@402: \interaction{template.simple.datekeyword}
igor@402:
igor@402: \section{Escape sequences}
igor@402: \label{sec:template:escape}
igor@402:
igor@402: Mercurial's templating engine recognises the most commonly used escape
igor@402: sequences in strings. When it sees a backslash (``\Verb+\+'')
igor@402: character, it looks at the following character and substitutes the two
igor@402: characters with a single replacement, as described below.
igor@402:
igor@402: \begin{itemize}
igor@402: \item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
igor@402: ASCII~134.
igor@402: \item[\Verb+\textbackslash n+] Newline, ASCII~12.
igor@402: \item[\Verb+\textbackslash r+] Carriage return, ASCII~15.
igor@402: \item[\Verb+\textbackslash t+] Tab, ASCII~11.
igor@402: \item[\Verb+\textbackslash v+] Vertical tab, ASCII~13.
igor@402: \item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173.
igor@402: \item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175.
igor@402: \end{itemize}
igor@402:
igor@402: As indicated above, if you want the expansion of a template to contain
igor@402: a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you
igor@402: must escape it.
igor@402:
igor@402: \section{Filtering keywords to change their results}
igor@402: \label{sec:template:filter}
igor@402:
igor@402: Some of the results of template expansion are not immediately easy to
igor@402: use. Mercurial lets you specify an optional chain of \emph{filters}
igor@402: to modify the result of expanding a keyword. You have already seen a
igor@402: common filter, \tplkwfilt{date}{isodate}, in action above, to make a
igor@402: date readable.
igor@402:
igor@402: Below is a list of the most commonly used filters that Mercurial
igor@402: supports. While some filters can be applied to any text, others can
igor@402: only be used in specific circumstances. The name of each filter is
igor@402: followed first by an indication of where it can be used, then a
igor@402: description of its effect.
igor@402:
igor@402: \begin{itemize}
igor@402: \item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+
+''
igor@402: tag before the end of every line except the last. For example,
igor@402: ``\Verb+foo\nbar+'' becomes ``\Verb+foo
\nbar+''.
igor@402: \item[\tplkwfilt{date}{age}] \tplkword{date} keyword. Render the
igor@402: age of the date, relative to the current time. Yields a string like
igor@402: ``\Verb+10 minutes+''.
igor@402: \item[\tplfilter{basename}] Any text, but most useful for the
igor@402: \tplkword{files} keyword and its relatives. Treat the text as a
igor@402: path, and return the basename. For example, ``\Verb+foo/bar/baz+''
igor@402: becomes ``\Verb+baz+''.
igor@402: \item[\tplkwfilt{date}{date}] \tplkword{date} keyword. Render a date
igor@402: in a similar format to the Unix \tplkword{date} command, but with
igor@402: timezone included. Yields a string like
igor@402: ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
igor@402: \item[\tplkwfilt{author}{domain}] Any text, but most useful for the
igor@402: \tplkword{author} keyword. Finds the first string that looks like
igor@402: an email address, and extract just the domain component. For
igor@402: example, ``\Verb+Bryan O'Sullivan +'' becomes
igor@402: ``\Verb+serpentine.com+''.
igor@402: \item[\tplkwfilt{author}{email}] Any text, but most useful for the
igor@402: \tplkword{author} keyword. Extract the first string that looks like
igor@402: an email address. For example,
igor@402: ``\Verb+Bryan O'Sullivan +'' becomes
igor@402: ``\Verb+bos@serpentine.com+''.
igor@402: \item[\tplfilter{escape}] Any text. Replace the special XML/XHTML
igor@402: characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with
igor@402: XML entities.
igor@402: \item[\tplfilter{fill68}] Any text. Wrap the text to fit in 68
igor@402: columns. This is useful before you pass text through the
igor@402: \tplfilter{tabindent} filter, and still want it to fit in an
igor@402: 80-column fixed-font window.
igor@402: \item[\tplfilter{fill76}] Any text. Wrap the text to fit in 76
igor@402: columns.
igor@402: \item[\tplfilter{firstline}] Any text. Yield the first line of text,
igor@402: without any trailing newlines.
igor@402: \item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the
igor@402: date as a pair of readable numbers. Yields a string like
igor@402: ``\Verb+1157407993 25200+''.
igor@402: \item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the
igor@402: date as a text string in ISO~8601 format. Yields a string like
igor@402: ``\Verb+2006-09-04 15:13:13 -0700+''.
igor@402: \item[\tplfilter{obfuscate}] Any text, but most useful for the
igor@402: \tplkword{author} keyword. Yield the input text rendered as a
igor@402: sequence of XML entities. This helps to defeat some particularly
igor@402: stupid screen-scraping email harvesting spambots.
igor@402: \item[\tplkwfilt{author}{person}] Any text, but most useful for the
igor@402: \tplkword{author} keyword. Yield the text before an email address.
igor@402: For example, ``\Verb+Bryan O'Sullivan +''
igor@402: becomes ``\Verb+Bryan O'Sullivan+''.
igor@402: \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a
igor@402: date using the same format used in email headers. Yields a string
igor@402: like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
igor@402: \item[\tplkwfilt{node}{short}] Changeset hash. Yield the short form
igor@402: of a changeset hash, i.e.~a 12-byte hexadecimal string.
igor@402: \item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render
igor@402: the year, month, and day of the date. Yields a string like
igor@402: ``\Verb+2006-09-04+''.
igor@402: \item[\tplfilter{strip}] Any text. Strip all leading and trailing
igor@402: whitespace from the string.
igor@402: \item[\tplfilter{tabindent}] Any text. Yield the text, with every line
igor@402: except the first starting with a tab character.
igor@402: \item[\tplfilter{urlescape}] Any text. Escape all characters that are
igor@402: considered ``special'' by URL parsers. For example, \Verb+foo bar+
igor@402: becomes \Verb+foo%20bar+.
igor@402: \item[\tplkwfilt{author}{user}] Any text, but most useful for the
igor@402: \tplkword{author} keyword. Return the ``user'' portion of an email
igor@402: address. For example,
igor@402: ``\Verb+Bryan O'Sullivan +'' becomes
igor@402: ``\Verb+bos+''.
igor@402: \end{itemize}
igor@402:
igor@402: \begin{figure}
igor@402: \interaction{template.simple.manyfilters}
igor@402: \caption{Template filters in action}
igor@402: \label{fig:template:filters}
igor@402: \end{figure}
igor@402:
igor@402: \begin{note}
igor@402: If you try to apply a filter to a piece of data that it cannot
igor@402: process, Mercurial will fail and print a Python exception. For
igor@402: example, trying to run the output of the \tplkword{desc} keyword
igor@402: into the \tplkwfilt{date}{isodate} filter is not a good idea.
igor@402: \end{note}
igor@402:
igor@402: \subsection{Combining filters}
igor@402:
igor@402: It is easy to combine filters to yield output in the form you would
igor@402: like. The following chain of filters tidies up a description, then
igor@402: makes sure that it fits cleanly into 68 columns, then indents it by a
igor@402: further 8~characters (at least on Unix-like systems, where a tab is
igor@402: conventionally 8~characters wide).
igor@402:
igor@402: \interaction{template.simple.combine}
igor@402:
igor@402: Note the use of ``\Verb+\t+'' (a tab character) in the template to
igor@402: force the first line to be indented; this is necessary since
igor@402: \tplkword{tabindent} indents all lines \emph{except} the first.
igor@402:
igor@402: Keep in mind that the order of filters in a chain is significant. The
igor@402: first filter is applied to the result of the keyword; the second to
igor@402: the result of the first filter; and so on. For example, using
igor@402: \Verb+fill68|tabindent+ gives very different results from
igor@402: \Verb+tabindent|fill68+.
igor@402:
igor@402:
igor@402: \section{From templates to styles}
igor@402:
igor@402: A command line template provides a quick and simple way to format some
igor@402: output. Templates can become verbose, though, and it's useful to be
igor@402: able to give a template a name. A style file is a template with a
igor@402: name, stored in a file.
igor@402:
igor@402: More than that, using a style file unlocks the power of Mercurial's
igor@402: templating engine in ways that are not possible using the command line
igor@402: \hgopt{log}{--template} option.
igor@402:
igor@402: \subsection{The simplest of style files}
igor@402:
igor@402: Our simple style file contains just one line:
igor@402:
igor@402: \interaction{template.simple.rev}
igor@402:
igor@402: This tells Mercurial, ``if you're printing a changeset, use the text
igor@402: on the right as the template''.
igor@402:
igor@402: \subsection{Style file syntax}
igor@402:
igor@402: The syntax rules for a style file are simple.
igor@402:
igor@402: \begin{itemize}
igor@402: \item The file is processed one line at a time.
igor@402:
igor@402: \item Leading and trailing white space are ignored.
igor@402:
igor@402: \item Empty lines are skipped.
igor@402:
igor@402: \item If a line starts with either of the characters ``\texttt{\#}'' or
igor@402: ``\texttt{;}'', the entire line is treated as a comment, and skipped
igor@402: as if empty.
igor@402:
igor@402: \item A line starts with a keyword. This must start with an
igor@402: alphabetic character or underscore, and can subsequently contain any
igor@402: alphanumeric character or underscore. (In regexp notation, a
igor@402: keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.)
igor@402:
igor@402: \item The next element must be an ``\texttt{=}'' character, which can
igor@402: be preceded or followed by an arbitrary amount of white space.
igor@402:
igor@402: \item If the rest of the line starts and ends with matching quote
igor@402: characters (either single or double quote), it is treated as a
igor@402: template body.
igor@402:
igor@402: \item If the rest of the line \emph{does not} start with a quote
igor@402: character, it is treated as the name of a file; the contents of this
igor@402: file will be read and used as a template body.
igor@402: \end{itemize}
igor@402:
igor@402: \section{Style files by example}
igor@402:
igor@402: To illustrate how to write a style file, we will construct a few by
igor@402: example. Rather than provide a complete style file and walk through
igor@402: it, we'll mirror the usual process of developing a style file by
igor@402: starting with something very simple, and walking through a series of
igor@402: successively more complete examples.
igor@402:
igor@402: \subsection{Identifying mistakes in style files}
igor@402:
igor@402: If Mercurial encounters a problem in a style file you are working on,
igor@402: it prints a terse error message that, once you figure out what it
igor@402: means, is actually quite useful.
igor@402:
igor@402: \interaction{template.svnstyle.syntax.input}
igor@402:
igor@402: Notice that \filename{broken.style} attempts to define a
igor@402: \texttt{changeset} keyword, but forgets to give any content for it.
igor@402: When instructed to use this style file, Mercurial promptly complains.
igor@402:
igor@402: \interaction{template.svnstyle.syntax.error}
igor@402:
igor@402: This error message looks intimidating, but it is not too hard to
igor@402: follow.
igor@402:
igor@402: \begin{itemize}
igor@402: \item The first component is simply Mercurial's way of saying ``I am
igor@402: giving up''.
igor@402: \begin{codesample4}
igor@402: \textbf{abort:} broken.style:1: parse error
igor@402: \end{codesample4}
igor@402:
igor@402: \item Next comes the name of the style file that contains the error.
igor@402: \begin{codesample4}
igor@402: abort: \textbf{broken.style}:1: parse error
igor@402: \end{codesample4}
igor@402:
igor@402: \item Following the file name is the line number where the error was
igor@402: encountered.
igor@402: \begin{codesample4}
igor@402: abort: broken.style:\textbf{1}: parse error
igor@402: \end{codesample4}
igor@402:
igor@402: \item Finally, a description of what went wrong.
igor@402: \begin{codesample4}
igor@402: abort: broken.style:1: \textbf{parse error}
igor@402: \end{codesample4}
igor@402: The description of the problem is not always clear (as in this
igor@402: case), but even when it is cryptic, it is almost always trivial to
igor@402: visually inspect the offending line in the style file and see what
igor@402: is wrong.
igor@402: \end{itemize}
igor@402:
igor@402: \subsection{Uniquely identifying a repository}
igor@402:
igor@402: If you would like to be able to identify a Mercurial repository
igor@402: ``fairly uniquely'' using a short string as an identifier, you can
igor@402: use the first revision in the repository.
igor@402: \interaction{template.svnstyle.id}
igor@402: This is not guaranteed to be unique, but it is nevertheless useful in
igor@402: many cases.
igor@402: \begin{itemize}
igor@402: \item It will not work in a completely empty repository, because such
igor@402: a repository does not have a revision~zero.
igor@402: \item Neither will it work in the (extremely rare) case where a
igor@402: repository is a merge of two or more formerly independent
igor@402: repositories, and you still have those repositories around.
igor@402: \end{itemize}
igor@402: Here are some uses to which you could put this identifier:
igor@402: \begin{itemize}
igor@402: \item As a key into a table for a database that manages repositories
igor@402: on a server.
igor@402: \item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple.
igor@402: Save this information away when you run an automated build or other
igor@402: activity, so that you can ``replay'' the build later if necessary.
igor@402: \end{itemize}
igor@402:
igor@402: \subsection{Mimicking Subversion's output}
igor@402:
igor@402: Let's try to emulate the default output format used by another
igor@402: revision control tool, Subversion.
igor@402: \interaction{template.svnstyle.short}
igor@402:
igor@402: Since Subversion's output style is fairly simple, it is easy to
igor@402: copy-and-paste a hunk of its output into a file, and replace the text
igor@402: produced above by Subversion with the template values we'd like to see
igor@402: expanded.
igor@402: \interaction{template.svnstyle.template}
igor@402:
igor@402: There are a few small ways in which this template deviates from the
igor@402: output produced by Subversion.
igor@402: \begin{itemize}
igor@402: \item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep
igor@402: 2006}'' in the example output above) in parentheses. Mercurial's
igor@402: templating engine does not provide a way to display a date in this
igor@402: format without also printing the time and time zone.
igor@402: \item We emulate Subversion's printing of ``separator'' lines full of
igor@402: ``\texttt{-}'' characters by ending the template with such a line.
igor@402: We use the templating engine's \tplkword{header} keyword to print a
igor@402: separator line as the first line of output (see below), thus
igor@402: achieving similar output to Subversion.
igor@402: \item Subversion's output includes a count in the header of the number
igor@402: of lines in the commit message. We cannot replicate this in
igor@402: Mercurial; the templating engine does not currently provide a filter
igor@402: that counts the number of items it is passed.
igor@402: \end{itemize}
igor@402: It took me no more than a minute or two of work to replace literal
igor@402: text from an example of Subversion's output with some keywords and
igor@402: filters to give the template above. The style file simply refers to
igor@402: the template.
igor@402: \interaction{template.svnstyle.style}
igor@402:
igor@402: We could have included the text of the template file directly in the
igor@402: style file by enclosing it in quotes and replacing the newlines with
igor@402: ``\verb!\n!'' sequences, but it would have made the style file too
igor@402: difficult to read. Readability is a good guide when you're trying to
igor@402: decide whether some text belongs in a style file, or in a template
igor@402: file that the style file points to. If the style file will look too
igor@402: big or cluttered if you insert a literal piece of text, drop it into a
igor@402: template instead.
igor@402:
igor@402: %%% Local Variables:
igor@402: %%% mode: latex
igor@402: %%% TeX-master: "00book"
igor@402: %%% End: