hgbook
view en/template.tex @ 83:b476081a9c04
Much progress in template chapter.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Tue Oct 03 13:03:42 2006 -0700 (2006-10-03) |
| parents | ea951cfb5cd9 |
| children | a239cd51dcd3 |
line source
1 \chapter{Customising the output of Mercurial}
2 \label{chap:template}
4 Mercurial provides a powerful mechanism to let you control how it
5 displays information. The mechanism is based on templates. You can
6 use templates to generate specific output for a single command, or to
7 customise the entire appearance of the built-in web interface.
9 \section{Using precanned output styles}
10 \label{sec:style}
12 Packaged with Mercurial are some output styles that you can use
13 immediately. A style is simply a precanned template that someone
14 wrote and installed somewhere that Mercurial can find.
16 Before we take a look at Mercurial's bundled styles, let's review its
17 normal output.
19 \interaction{template.simple.normal}
21 This is somewhat informative, but it takes up a lot of space---five
22 lines of output per changeset. The \texttt{compact} style reduces
23 this to three lines, presented in a sparse manner.
25 \interaction{template.simple.compact}
27 The \texttt{changelog} style hints at the expressive power of
28 Mercurial's templating engine. This style attempts to follow the GNU
29 Project's changelog guidelines\cite{web:changelog}.
31 \interaction{template.simple.changelog}
33 You will not be shocked to learn that Mercurial's default output style
34 is named \texttt{default}.
36 \subsection{Setting a default style}
38 You can modify the output style that Mercurial will use for every
39 command by editing your \hgrc\ file, naming the style you would
40 prefer to use.
42 \begin{codesample2}
43 [ui]
44 style = compact
45 \end{codesample2}
47 If you write a style of your own, you can use it by either providing
48 the path to your style file, or copying your style file into a
49 location where Mercurial can find it (typically the \texttt{templates}
50 subdirectory of your Mercurial install directory).
52 \section{Commands that support styles and templates}
54 All of Mercurial's ``\texttt{log}-like'' commands let you use styles
55 and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and
56 \hgcmd{tip}.
58 As I write this manual, these are so far the only commands that
59 support styles and templates. Since these are the most important
60 commands that need customisable output, there has been little pressure
61 from the Mercurial user community to add style and template support to
62 other commands.
64 \section{The basics of templating}
66 At its simplest, a Mercurial template is a piece of text. Some of the
67 text never changes, while other parts are \emph{expanded}, or replaced
68 with new text, when necessary.
70 Before we continue, let's look again at a simple example of
71 Mercurial's normal output.
73 \interaction{template.simple.normal}
75 Now, let's run the same command, but using a template to change its
76 output.
78 \interaction{template.simple.simplest}
80 The example above illustrates the simplest possible template; it's
81 just a piece of static text, printed once for each changeset. The
82 \hgopt{log}{--template} option to the \hgcmd{log} command tells
83 Mercurial to use the given text as the template when printing each
84 changeset.
86 Notice that the template string above ends with the text
87 ``\Verb+\n+''. This is an \emph{escape sequence}, telling Mercurial
88 to print a newline at the end of each template item. If you omit this
89 newline, Mercurial will run each piece of output together. See
90 section~\ref{sec:template:escape} for more details of escape sequences.
92 A template that prints a fixed string of text all the time isn't very
93 useful; let's try something a bit more complex.
95 \interaction{template.simple.simplesub}
97 As you can see, the string ``\Verb+{desc}+'' in the template has been
98 replaced in the output with the description of each changeset. Every
99 time Mercurial finds text enclosed in curly braces (``\texttt{\{}''
100 and ``\texttt{\}}''), it will try to replace the braces and text with
101 the expansion of whatever is inside. To print a literal curly brace,
102 you must escape it, as described in section~\ref{sec:template:escape}.
104 \section{Common template keywords}
105 \label{sec:template:keyword}
107 You can start writing simple templates immediately using the keywords
108 below.
110 \begin{itemize}
111 \item[\tplkword{author}] String. The unmodified author of the changeset.
112 \item[\tplkword{date}] Date information. The date when the changeset
113 was committed. This is \emph{not} human-readable; you must pass it
114 through a filter that will render it appropriately. See
115 section~\ref{sec:template:filter} for more information on filters.
116 The date is expressed as a pair of numbers. The first number is a
117 Unix UTC timestamp (seconds since January 1, 1970); the second is
118 the offset of the committer's timezone from UTC, in seconds.
119 \item[\tplkword{desc}] String. The text of the changeset description.
120 \item[\tplkword{files}] List of strings. All files modified, added, or
121 removed by this changeset.
122 \item[\tplkword{file\_adds}] List of strings. Files added by this
123 changeset.
124 \item[\tplkword{file\_dels}] List of strings. Files removed by this
125 changeset.
126 \item[\tplkword{node}] String. The changeset identification hash, as a
127 40-character hexadecimal string.
128 \item[\tplkword{parents}] List of strings. The parents of the
129 changeset.
130 \item[\tplkword{rev}] Integer. The repository-local changeset revision
131 number.
132 \item[\tplkword{tags}] List of strings. Any tags associated with the
133 changeset.
134 \end{itemize}
136 A few simple experiments will show us what to expect when we use these
137 keywords; you can see the results in
138 figure~\ref{fig:template:keywords}.
140 \begin{figure}
141 \interaction{template.simple.keywords}
142 \caption{Template keywords in use}
143 \label{fig:template:keywords}
144 \end{figure}
146 As we noted above, the date keyword does not produce human-readable
147 output, so we must treat it specially. This involves using a
148 \emph{filter}, about which more in section~\ref{sec:template:filter}.
150 \interaction{template.simple.datekeyword}
152 \section{Escape sequences}
153 \label{sec:template:escape}
155 Mercurial's templating engine recognises the most commonly used escape
156 sequences in strings. When it sees a backslash (``\Verb+\+'')
157 character, it looks at the following character and substitutes the two
158 characters with a single replacement, as described below.
160 \begin{itemize}
161 \item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
162 ASCII~134.
163 \item[\Verb+\textbackslash n+] Newline, ASCII~12.
164 \item[\Verb+\textbackslash r+] Carriage return, ASCII~15.
165 \item[\Verb+\textbackslash t+] Tab, ASCII~11.
166 \item[\Verb+\textbackslash v+] Vertical tab, ASCII~13.
167 \item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173.
168 \item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175.
169 \end{itemize}
171 As indicated above, if you want the expansion of a template to contain
172 a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you
173 must escape it.
175 \section{Filtering keywords to change their results}
176 \label{sec:template:filter}
178 Some of the results of template expansion are not immediately easy to
179 use. Mercurial lets you specify an optional chain of \emph{filters}
180 to modify the result of expanding a keyword. You have already seen a
181 common filter, \tplkwfilt{date}{isodate}, in action above, to make a
182 date readable.
184 Below is a list of the most commonly used filters that Mercurial
185 supports. While some filters can be applied to any text, others can
186 only be used in specific circumstances. The name of each filter is
187 followed first by an indication of where it can be used, then a
188 description of its effect.
190 \begin{itemize}
191 \item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+''
192 tag before the end of every line except the last. For example,
193 ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''.
194 \item[\tplkwfilt{date}{age}] \tplkword{date} keyword. Render the
195 age of the date, relative to the current time. Yields a string like
196 ``\Verb+10 minutes+''.
197 \item[\tplfilter{basename}] Any text, but most useful for the
198 \tplkword{files} keyword and its relatives. Treat the text as a
199 path, and return the basename. For example, ``\Verb+foo/bar/baz+''
200 becomes ``\Verb+baz+''.
201 \item[\tplkwfilt{date}{date}] \tplkword{date} keyword. Render a date
202 in a similar format to the Unix \tplkword{date} command, but with
203 timezone included. Yields a string like
204 ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
205 \item[\tplkwfilt{author}{domain}] Any text, but most useful for the
206 \tplkword{author} keyword. Finds the first string that looks like
207 an email address, and extract just the domain component. For
208 example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
209 ``\Verb+serpentine.com+''.
210 \item[\tplkwfilt{author}{email}] Any text, but most useful for the
211 \tplkword{author} keyword. Extract the first string that looks like
212 an email address. For example,
213 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
214 ``\Verb+bos@serpentine.com+''.
215 \item[\tplfilter{escape}] Any text. Replace the special XML/XHTML
216 characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with
217 XML entities.
218 \item[\tplfilter{fill68}] Any text. Wrap the text to fit in 68
219 columns. This is useful before you pass text through the
220 \tplfilter{tabindent} filter, and still want it to fit in an
221 80-column fixed-font window.
222 \item[\tplfilter{fill76}] Any text. Wrap the text to fit in 76
223 columns.
224 \item[\tplfilter{firstline}] Any text. Yield the first line of text,
225 without any trailing newlines.
226 \item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the
227 date as a pair of readable numbers. Yields a string like
228 ``\Verb+1157407993 25200+''.
229 \item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the
230 date as a text string in ISO~8601 format. Yields a string like
231 ``\Verb+2006-09-04 15:13:13 -0700+''.
232 \item[\tplfilter{obfuscate}] Any text, but most useful for the
233 \tplkword{author} keyword. Yield the input text rendered as a
234 sequence of XML entities. This helps to defeat some particularly
235 stupid screen-scraping email harvesting spambots.
236 \item[\tplkwfilt{author}{person}] Any text, but most useful for the
237 \tplkword{author} keyword. Yield the text before an email address.
238 For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+''
239 becomes ``\Verb+Bryan O'Sullivan+''.
240 \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a
241 date using the same format used in email headers. Yields a string
242 like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
243 \item[\tplkwfilt{node}{short}] Changeset hash. Yield the short form
244 of a changeset hash, i.e.~a 12-byte hexadecimal string.
245 \item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render
246 the year, month, and day of the date. Yields a string like
247 ``\Verb+2006-09-04+''.
248 \item[\tplfilter{strip}] Any text. Strip all leading and trailing
249 whitespace from the string.
250 \item[\tplfilter{tabindent}] Any text. Yield the text, with every line
251 except the first starting with a tab character.
252 \item[\tplfilter{urlescape}] Any text. Escape all characters that are
253 considered ``special'' by URL parsers. For example, \Verb+foo bar+
254 becomes \Verb+foo%20bar+.
255 \item[\tplkwfilt{author}{user}] Any text, but most useful for the
256 \tplkword{author} keyword. Return the ``user'' portion of an email
257 address. For example,
258 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
259 ``\Verb+bos+''.
260 \end{itemize}
262 \begin{figure}
263 \interaction{template.simple.manyfilters}
264 \caption{Template filters in action}
265 \label{fig:template:filters}
266 \end{figure}
268 \begin{note}
269 If you try to apply a filter to a piece of data that it cannot
270 process, Mercurial will fail and print a Python exception. For
271 example, trying to run the output of the \tplkword{desc} keyword
272 into the \tplkwfilt{date}{isodate} filter is not a good idea.
273 \end{note}
275 \subsection{Combining filters}
277 It is easy to combine filters to yield output in the form you would
278 like. The following chain of filters tidies up a description, then
279 makes sure that it fits cleanly into 68 columns, then indents it by a
280 further 8~characters (at least on Unix-like systems, where a tab is
281 conventionally 8~characters wide).
283 \interaction{template.simple.combine}
285 Note the use of ``\Verb+\t+'' (a tab character) in the template to
286 force the first line to be indented; this is necessary since
287 \tplkword{tabindent} indents all lines \emph{except} the first.
289 Keep in mind that the order of filters in a chain is significant. The
290 first filter is applied to the result of the keyword; the second to
291 the result of the first filter; and so on. For example, using
292 \Verb+fill68|tabindent+ gives very different results from
293 \Verb+tabindent|fill68+.
296 \section{From templates to styles}
298 A command line template provides a quick and simple way to format some
299 output. Templates can become verbose, though, and it's useful to be
300 able to give a template a name. A style file is a template with a
301 name, stored in a file.
303 More than that, using a style file unlocks the power of Mercurial's
304 templating engine in ways that are not possible using the command line
305 \hgopt{log}{--template} option.
307 \subsection{The simplest of style files}
309 Our simple style file contains just one line:
311 \interaction{template.simple.rev}
313 This tells Mercurial, ``if you're printing a changeset, use the text
314 on the right as the template''.
316 \subsection{Style file syntax}
318 The syntax rules for a style file are simple.
320 \begin{itemize}
321 \item The file is processed one line at a time.
323 \item Leading and trailing white space are ignored.
325 \item Empty lines are skipped.
327 \item If a line starts with either of the characters ``\texttt{\#}'' or
328 ``\texttt{;}'', the entire line is treated as a comment, and skipped
329 as if empty.
331 \item A line starts with a keyword. This must start with an
332 alphabetic character or underscore, and can subsequently contain any
333 alphanumeric character or underscore. (In regexp notation, a
334 keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.)
336 \item The next element must be an ``\texttt{=}'' character, which can
337 be preceded or followed by an arbitrary amount of white space.
339 \item If the rest of the line starts and ends with matching quote
340 characters (either single or double quote), it is treated as a
341 template body.
343 \item If the rest of the line \emph{does not} start with a quote
344 character, it is treated as the name of a file; the contents of this
345 file will be read and used as a template body.
346 \end{itemize}
348 \section{Style files by example}
350 To illustrate how to write a style file, we will construct a few by
351 example. Rather than provide a complete style file and walk through
352 it, we'll mirror the usual process of developing a style file by
353 starting with something very simple, and walking through a series of
354 successively more complete examples.
356 \subsection{Identifying mistakes in style files}
358 If Mercurial encounters a problem in a style file you are working on,
359 it prints a terse error message that, once you figure out what it
360 means, is actually quite useful.
362 \interaction{template.svnstyle.syntax.input}
364 Notice that \filename{broken.style} attempts to define a
365 \texttt{changeset} keyword, but forgets to give any content for it.
366 When instructed to use this style file, Mercurial promptly complains.
368 \interaction{template.svnstyle.syntax.error}
370 This error message looks intimidating, but it is not too hard to
371 follow.
373 \begin{itemize}
374 \item The first component is simply Mercurial's way of saying ``I am
375 giving up''.
376 \begin{codesample4}
377 \textbf{abort:} broken.style:1: parse error
378 \end{codesample4}
380 \item Next comes the name of the style file that contains the error.
381 \begin{codesample4}
382 abort: \textbf{broken.style}:1: parse error
383 \end{codesample4}
385 \item Following the file name is the line number where the error was
386 encountered.
387 \begin{codesample4}
388 abort: broken.style:\textbf{1}: parse error
389 \end{codesample4}
391 \item Finally, a description of what went wrong.
392 \begin{codesample4}
393 abort: broken.style:1: \textbf{parse error}
394 \end{codesample4}
395 The description of the problem is not always clear (as in this
396 case), but even when it is cryptic, it is almost always trivial to
397 visually inspect the offending line in the style file and see what
398 is wrong.
399 \end{itemize}
401 \subsection{Uniquely identifying a repository}
403 If you would like to be able to identify a Mercurial repository
404 ``fairly uniquely'' using a short string as an identifier, you can
405 use the first revision in the repository.
406 \interaction{template.svnstyle.id}
407 This is not guaranteed to be unique, but it is nevertheless useful in
408 many cases.
409 \begin{itemize}
410 \item It will not work in a completely empty repository, because such
411 a repository does not have a revision~zero.
412 \item Neither will it work in the (extremely rare) case where a
413 repository is a merge of two or more formerly independent
414 repositories, and you still have those repositories around.
415 \end{itemize}
416 Here are some uses to which you could put this identifier:
417 \begin{itemize}
418 \item As a key into a table for a database that manages repositories
419 on a server.
420 \item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple.
421 Save this information away when you run an automated build or other
422 activity, so that you can ``replay'' the build later if necessary.
423 \end{itemize}
425 \subsection{Mimicking Subversion's output}
427 Let's try to emulate the default output format used by another
428 revision control tool, Subversion.
429 \interaction{template.svnstyle.short}
431 Since Subversion's output style is fairly simple, it is easy to
432 copy-and-paste a hunk of its output into a file, and replace the text
433 produced above by Subversion with the template values we'd like to see
434 expanded.
435 \interaction{template.svnstyle.template}
437 There are a few small ways in which this template deviates from the
438 output produced by Subversion.
439 \begin{itemize}
440 \item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep
441 2006}'' in the example output above) in parentheses. Mercurial's
442 templating engine does not provide a way to display a date in this
443 format without also printing the time and time zone.
444 \item We emulate Subversion's printing of ``separator'' lines full of
445 ``\texttt{-}'' characters by ending the template with such a line.
446 We use the templating engine's \tplkword{header} keyword to print a
447 separator line as the first line of output (see below), thus
448 achieving similar output to Subversion.
449 \item Subversion's output includes a count in the header of the number
450 of lines in the commit message. We cannot replicate this in
451 Mercurial; the templating engine does not currently provide a filter
452 that counts the number of items it is passed.
453 \end{itemize}
454 It took me no more than a minute or two of work to replace literal
455 text from an example of Subversion's output with some keywords and
456 filters to give the template above. The style file simply refers to
457 the template.
458 \interaction{template.svnstyle.style}
460 We could have included the text of the template file directly in the
461 style file by enclosing it in quotes and replacing the newlines with
462 ``\texttt{\\n}'' sequences, but it would have made the style file too
463 difficult to read. Readability is a good guide when you're trying to
464 decide whether some text belongs in a style file, or in a template
465 file that the style file points to. If the style file will look too
466 big or cluttered if you insert a literal piece of text, drop it into a
467 template instead.
469 %%% Local Variables:
470 %%% mode: latex
471 %%% TeX-master: "00book"
472 %%% End: