| rev |
line source |
|
bos@80
|
1 \chapter{Customising the output of Mercurial}
|
|
bos@80
|
2 \label{chap:template}
|
|
bos@80
|
3
|
|
bos@80
|
4 Mercurial provides a powerful mechanism to let you control how it
|
|
bos@80
|
5 displays information. The mechanism is based on templates. You can
|
|
bos@80
|
6 use templates to generate specific output for a single command, or to
|
|
bos@80
|
7 customise the entire appearance of the built-in web interface.
|
|
bos@80
|
8
|
|
bos@80
|
9 \section{Using precanned output styles}
|
|
bos@80
|
10 \label{sec:style}
|
|
bos@80
|
11
|
|
bos@80
|
12 Packaged with Mercurial are some output styles that you can use
|
|
bos@80
|
13 immediately. A style is simply a precanned template that someone
|
|
bos@80
|
14 wrote.
|
|
bos@80
|
15
|
|
bos@80
|
16 Before we take a look at Mercurial's bundled styles, let's review its
|
|
bos@80
|
17 normal output.
|
|
bos@80
|
18
|
|
bos@80
|
19 \interaction{template.simple.normal}
|
|
bos@80
|
20
|
|
bos@80
|
21 This is somewhat informative, but it takes up a lot of space---five
|
|
bos@80
|
22 lines of output per changeset. The \texttt{compact} style reduces
|
|
bos@80
|
23 this to three lines, presented in a sparse manner.
|
|
bos@80
|
24
|
|
bos@80
|
25 \interaction{template.simple.compact}
|
|
bos@80
|
26
|
|
bos@80
|
27 The \texttt{changelog} style hints at the expressive power of
|
|
bos@80
|
28 Mercurial's templating engine. This style attempts to follow the GNU
|
|
bos@80
|
29 Project's changelog guidelines\cite{web:changelog}.
|
|
bos@80
|
30
|
|
bos@80
|
31 \interaction{template.simple.changelog}
|
|
bos@80
|
32
|
|
bos@80
|
33 You will not be shocked to learn that Mercurial's default output style
|
|
bos@80
|
34 is named \texttt{default}.
|
|
bos@80
|
35
|
|
bos@80
|
36 \subsection{Setting an output style to use}
|
|
bos@80
|
37
|
|
bos@80
|
38 You can modify the output style that Mercurial will use for every
|
|
bos@80
|
39 command by editing your \hgrc\ file, naming the style you would
|
|
bos@80
|
40 prefer to use.
|
|
bos@80
|
41
|
|
bos@80
|
42 \begin{codesample2}
|
|
bos@80
|
43 [ui]
|
|
bos@80
|
44 style = compact
|
|
bos@80
|
45 \end{codesample2}
|
|
bos@80
|
46
|
|
bos@80
|
47 If you write a style of your own, you can use it by either providing
|
|
bos@80
|
48 the path to your style file, or copying your style file into a
|
|
bos@80
|
49 location where Mercurial can find it (typically the \texttt{templates}
|
|
bos@80
|
50 subdirectory of your Mercurial install directory).
|
|
bos@80
|
51
|
|
bos@80
|
52 \section{Commands that support styles and templates}
|
|
bos@80
|
53
|
|
bos@80
|
54 All of Mercurial's ``\texttt{log}-like'' commands let you use styles
|
|
bos@80
|
55 and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and
|
|
bos@80
|
56 \hgcmd{tip}.
|
|
bos@80
|
57
|
|
bos@80
|
58 As I write this manual, these are so far the only commands that
|
|
bos@80
|
59 support styles and templates. Since these are the most important
|
|
bos@80
|
60 commands that need customisable output, there has been little pressure
|
|
bos@80
|
61 from the Mercurial user community to add style and template support to
|
|
bos@80
|
62 other commands.
|
|
bos@80
|
63
|
|
bos@80
|
64 \section{The basics of templating}
|
|
bos@80
|
65
|
|
bos@80
|
66 At its simplest, a Mercurial template is a piece of text. Some of the
|
|
bos@80
|
67 text never changes, while other parts are \emph{expanded}, or replaced
|
|
bos@80
|
68 with new text, when necessary.
|
|
bos@80
|
69
|
|
bos@80
|
70 Before we continue, let's look again at a simple example of
|
|
bos@80
|
71 Mercurial's normal output.
|
|
bos@80
|
72
|
|
bos@80
|
73 \interaction{template.simple.normal}
|
|
bos@80
|
74
|
|
bos@80
|
75 Now, let's run the same command, but using a template to change its
|
|
bos@80
|
76 output.
|
|
bos@80
|
77
|
|
bos@80
|
78 \interaction{template.simple.simplest}
|
|
bos@80
|
79
|
|
bos@80
|
80 The example above illustrates the simplest possible template; it's
|
|
bos@80
|
81 just a piece of static text, printed once for each changeset. The
|
|
bos@80
|
82 \hgopt{log}{--template} option to the \hgcmd{log} command tells
|
|
bos@80
|
83 Mercurial to use the given text as the template when printing each
|
|
bos@80
|
84 changeset.
|
|
bos@80
|
85
|
|
bos@80
|
86 Notice that the template string above ends with the text
|
|
bos@80
|
87 ``\Verb+\n+''. This is an \emph{escape sequence}, telling Mercurial
|
|
bos@80
|
88 to print a newline at the end of each template item. If you omit this
|
|
bos@80
|
89 newline, Mercurial will run each piece of output together. See
|
|
bos@80
|
90 section~\ref{sec:template:escape} for more details of escape sequences.
|
|
bos@80
|
91
|
|
bos@80
|
92 A template that prints a fixed string of text all the time isn't very
|
|
bos@80
|
93 useful; let's try something a bit more complex.
|
|
bos@80
|
94
|
|
bos@80
|
95 \interaction{template.simple.simplesub}
|
|
bos@80
|
96
|
|
bos@80
|
97 As you can see, the string ``\Verb+{desc}+'' in the template has been
|
|
bos@80
|
98 replaced in the output with the description of each changeset. Every
|
|
bos@80
|
99 time Mercurial finds text enclosed in curly braces (``\texttt{\{}''
|
|
bos@80
|
100 and ``\texttt{\}}''), it will try to replace the braces and text with
|
|
bos@80
|
101 the expansion of whatever is inside. To print a literal curly brace,
|
|
bos@80
|
102 you must escape it, as described in section~\ref{sec:template:escape}.
|
|
bos@80
|
103
|
|
bos@80
|
104 \section{Basic template keywords}
|
|
bos@80
|
105 \label{sec:template:keyword}
|
|
bos@80
|
106
|
|
bos@80
|
107 You can start writing simple templates immediately using the keywords
|
|
bos@80
|
108 below.
|
|
bos@80
|
109
|
|
bos@80
|
110 \begin{itemize}
|
|
bos@80
|
111 \item[\tplkword{author}] String. The unmodified author of the changeset.
|
|
bos@80
|
112 \item[\tplkword{date}] Date information. The date when the changeset
|
|
bos@80
|
113 was committed. This is \emph{not} human-readable; you must pass it
|
|
bos@80
|
114 through a filter that will render it appropriately. See
|
|
bos@80
|
115 section~\ref{sec:template:filter} for more information on filters.
|
|
bos@80
|
116 The date is expressed as a pair of numbers. The first number is a
|
|
bos@80
|
117 Unix UTC timestamp (seconds since January 1, 1970); the second is
|
|
bos@80
|
118 the offset of the committer's timezone from UTC, in seconds.
|
|
bos@80
|
119 \item[\tplkword{desc}] String. The text of the changeset description.
|
|
bos@80
|
120 \item[\tplkword{files}] List of strings. All files modified, added, or
|
|
bos@80
|
121 removed by this changeset.
|
|
bos@80
|
122 \item[\tplkword{file\_adds}] List of strings. Files added by this
|
|
bos@80
|
123 changeset.
|
|
bos@80
|
124 \item[\tplkword{file\_dels}] List of strings. Files removed by this
|
|
bos@80
|
125 changeset.
|
|
bos@80
|
126 \item[\tplkword{node}] String. The changeset identification hash, as a
|
|
bos@80
|
127 40-character hexadecimal string.
|
|
bos@80
|
128 \item[\tplkword{parents}] List of strings. The parents of the
|
|
bos@80
|
129 changeset.
|
|
bos@80
|
130 \item[\tplkword{rev}] Integer. The repository-local changeset revision
|
|
bos@80
|
131 number.
|
|
bos@80
|
132 \item[\tplkword{tags}] List of strings. Any tags associated with the
|
|
bos@80
|
133 changeset.
|
|
bos@80
|
134 \end{itemize}
|
|
bos@80
|
135
|
|
bos@80
|
136 A few simple experiments will show us what to expect when we use these
|
|
bos@80
|
137 keywords; you can see the results in
|
|
bos@80
|
138 figure~\ref{fig:template:keywords}.
|
|
bos@80
|
139
|
|
bos@80
|
140 \begin{figure}
|
|
bos@80
|
141 \interaction{template.simple.keywords}
|
|
bos@80
|
142 \caption{Template keywords in use}
|
|
bos@80
|
143 \label{fig:template:keywords}
|
|
bos@80
|
144 \end{figure}
|
|
bos@80
|
145
|
|
bos@80
|
146 As we noted above, the date keyword does not produce human-readable
|
|
bos@80
|
147 output, so we must treat it specially. This involves using a
|
|
bos@80
|
148 \emph{filter}, about which more in section~\ref{sec:template:filter}.
|
|
bos@80
|
149
|
|
bos@80
|
150 \interaction{template.simple.datekeyword}
|
|
bos@80
|
151
|
|
bos@80
|
152 \section{Escape sequences}
|
|
bos@80
|
153 \label{sec:template:escape}
|
|
bos@80
|
154
|
|
bos@80
|
155 Mercurial's templating engine recognises the most commonly used escape
|
|
bos@80
|
156 sequences in strings. When it sees a backslash (``\Verb+\+'')
|
|
bos@80
|
157 character, it looks at the following character and substitutes the two
|
|
bos@80
|
158 characters with a single replacement, as described below.
|
|
bos@80
|
159
|
|
bos@80
|
160 \begin{itemize}
|
|
bos@80
|
161 \item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
|
|
bos@80
|
162 ASCII~134.
|
|
bos@80
|
163 \item[\Verb+\textbackslash n+] Newline, ASCII~12.
|
|
bos@80
|
164 \item[\Verb+\textbackslash r+] Carriage return, ASCII~15.
|
|
bos@80
|
165 \item[\Verb+\textbackslash t+] Tab, ASCII~11.
|
|
bos@80
|
166 \item[\Verb+\textbackslash v+] Vertical tab, ASCII~13.
|
|
bos@80
|
167 \item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173.
|
|
bos@80
|
168 \item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175.
|
|
bos@80
|
169 \end{itemize}
|
|
bos@80
|
170
|
|
bos@80
|
171 As indicated above, if you want the expansion of a template to contain
|
|
bos@80
|
172 a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you
|
|
bos@80
|
173 must escape it.
|
|
bos@80
|
174
|
|
bos@80
|
175 \section{Filtering expanded keywords}
|
|
bos@80
|
176 \label{sec:template:filter}
|
|
bos@80
|
177
|
|
bos@80
|
178 Some of the results of template expansion are not entirely easy to
|
|
bos@80
|
179 use. Mercurial lets you specify an optional chain of \emph{filters}
|
|
bos@80
|
180 to modify the result of expanding a keyword. You have already seen a
|
|
bos@80
|
181 common filter, \tplkwfilt{date}{isodate}, in action above, to make a
|
|
bos@80
|
182 date readable.
|
|
bos@80
|
183
|
|
bos@80
|
184 \begin{itemize}
|
|
bos@80
|
185 \item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+''
|
|
bos@80
|
186 tag before the end of every line except the last. For example,
|
|
bos@80
|
187 ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''.
|
|
bos@80
|
188 \item[\tplkwfilt{date}{age}] \tplkword{date} keyword. Render the
|
|
bos@80
|
189 age of the date, relative to the current time. Yields a string like
|
|
bos@80
|
190 ``\Verb+10 minutes+''.
|
|
bos@80
|
191 \item[\tplfilter{basename}] Any text, but most useful for the
|
|
bos@80
|
192 \tplkword{files} keyword and its relatives. Treat the text as a
|
|
bos@80
|
193 path, and return the basename. For example, ``\Verb+foo/bar/baz+''
|
|
bos@80
|
194 becomes ``\Verb+baz+''.
|
|
bos@80
|
195 \item[\tplkwfilt{date}{date}] \tplkword{date} keyword. Render a date
|
|
bos@80
|
196 in a similar format to the Unix \tplkword{date} command, but with
|
|
bos@80
|
197 timezone included. Yields a string like
|
|
bos@80
|
198 ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
|
|
bos@80
|
199 \item[\tplkwfilt{author}{domain}] Any text, but most useful for the
|
|
bos@80
|
200 \tplkword{author} keyword. Finds the first string that looks like
|
|
bos@80
|
201 an email address, and extract just the domain component. For
|
|
bos@80
|
202 example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
|
|
bos@80
|
203 ``\Verb+serpentine.com+''.
|
|
bos@80
|
204 \item[\tplkwfilt{author}{email}] Any text, but most useful for the
|
|
bos@80
|
205 \tplkword{author} keyword. Extract the first string that looks like
|
|
bos@80
|
206 an email address. For example,
|
|
bos@80
|
207 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
|
|
bos@80
|
208 ``\Verb+bos@serpentine.com+''.
|
|
bos@80
|
209 \item[\tplfilter{escape}] Any text. Replace the special XML/XHTML
|
|
bos@80
|
210 characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with
|
|
bos@80
|
211 XML entities.
|
|
bos@80
|
212 \item[\tplfilter{fill68}] Any text. Wrap the text to fit in 68
|
|
bos@80
|
213 columns. This is useful before you pass text through the
|
|
bos@80
|
214 \tplfilter{tabindent} filter, and still want it to fit in an
|
|
bos@80
|
215 80-column fixed-font window.
|
|
bos@80
|
216 \item[\tplfilter{fill76}] Any text. Wrap the text to fit in 76
|
|
bos@80
|
217 columns.
|
|
bos@80
|
218 \item[\tplfilter{firstline}] Any text. Yield the first line of text,
|
|
bos@80
|
219 without any trailing newlines.
|
|
bos@80
|
220 \item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the
|
|
bos@80
|
221 date as a pair of readable numbers. Yields a string like
|
|
bos@80
|
222 ``\Verb+1157407993 25200+''.
|
|
bos@80
|
223 \item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the
|
|
bos@80
|
224 date as a text string in ISO~8601 format. Yields a string like
|
|
bos@80
|
225 ``\Verb+2006-09-04 15:13:13 -0700+''.
|
|
bos@80
|
226 \item[\tplfilter{obfuscate}] Any text, but most useful for the
|
|
bos@80
|
227 \tplkword{author} keyword. Yield the input text rendered as a
|
|
bos@80
|
228 sequence of XML entities. This helps to defeat some particularly
|
|
bos@80
|
229 stupid screen-scraping email harvesting spambots.
|
|
bos@80
|
230 \item[\tplkwfilt{author}{person}] Any text, but most useful for the
|
|
bos@80
|
231 \tplkword{author} keyword. Yield the text before an email address.
|
|
bos@80
|
232 For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+''
|
|
bos@80
|
233 becomes ``\Verb+Bryan O'Sullivan+''.
|
|
bos@80
|
234 \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a
|
|
bos@80
|
235 date using the same format used in email headers. Yields a string
|
|
bos@80
|
236 like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
|
|
bos@80
|
237 \item[\tplkwfilt{node}{short}] Changeset hash. Yield the short form
|
|
bos@80
|
238 of a changeset hash, i.e.~a 12-byte hexadecimal string.
|
|
bos@80
|
239 \item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render
|
|
bos@80
|
240 the year, month, and day of the date. Yields a string like
|
|
bos@80
|
241 ``\Verb+2006-09-04+''.
|
|
bos@80
|
242 \item[\tplfilter{strip}] Any text. Strip all leading and trailing
|
|
bos@80
|
243 whitespace from the string.
|
|
bos@80
|
244 \item[\tplfilter{tabindent}] Any text. Yield the text, with every line
|
|
bos@80
|
245 except the first starting with a tab character.
|
|
bos@80
|
246 \item[\tplfilter{urlescape}] Any text. Escape all characters that are
|
|
bos@80
|
247 considered ``special'' by URL parsers. For example, \Verb+foo bar+
|
|
bos@80
|
248 becomes \Verb+foo%20bar+.
|
|
bos@80
|
249 \item[\tplkwfilt{author}{user}] Any text, but most useful for the
|
|
bos@80
|
250 \tplkword{author} keyword. Return the ``user'' portion of an email
|
|
bos@80
|
251 address. For example,
|
|
bos@80
|
252 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
|
|
bos@80
|
253 ``\Verb+bos+''.
|
|
bos@80
|
254 \end{itemize}
|
|
bos@80
|
255
|
|
bos@80
|
256 \begin{figure}
|
|
bos@80
|
257 \interaction{template.simple.manyfilters}
|
|
bos@80
|
258 \caption{Template filters in action}
|
|
bos@80
|
259 \label{fig:template:filters}
|
|
bos@80
|
260 \end{figure}
|
|
bos@80
|
261
|
|
bos@80
|
262 \begin{note}
|
|
bos@80
|
263 If you try to apply a filter to a piece of data that it cannot
|
|
bos@80
|
264 process, Mercurial will fail and print a Python exception. For
|
|
bos@80
|
265 example, trying to run the output of the \tplkword{desc} keyword
|
|
bos@80
|
266 into the \tplkwfilt{date}{isodate} filter is not a good idea.
|
|
bos@80
|
267 \end{note}
|
|
bos@80
|
268
|
|
bos@80
|
269 \subsection{Combining filters}
|
|
bos@80
|
270
|
|
bos@80
|
271 It is easy to combine filters to yield output in the form you would
|
|
bos@80
|
272 like. The following chain of filters tidies up a description, then
|
|
bos@80
|
273 makes sure that it fits cleanly into 68 columns, then indents it by a
|
|
bos@80
|
274 further 8~characters (at least on Unix-like systems, where a tab is
|
|
bos@80
|
275 conventionally 8~characters wide).
|
|
bos@80
|
276
|
|
bos@80
|
277 \interaction{template.simple.combine}
|
|
bos@80
|
278
|
|
bos@80
|
279 Note the use of ``\Verb+\t+'' (a tab character) in the template to
|
|
bos@80
|
280 force the first line to be indented; this is necessary since
|
|
bos@80
|
281 \tplkword{tabindent} indents all lines \emph{except} the first.
|
|
bos@80
|
282
|
|
bos@80
|
283 Keep in mind that the order of filters in a chain is significant.
|
|
bos@80
|
284 Using \Verb+fill68|tabindent+ gives very different results from
|
|
bos@80
|
285 \Verb+tabindent|fill68+.
|
|
bos@76
|
286
|
|
bos@76
|
287 %%% Local Variables:
|
|
bos@76
|
288 %%% mode: latex
|
|
bos@76
|
289 %%% TeX-master: "00book"
|
|
bos@76
|
290 %%% End:
|
