##// END OF EJS Templates
help: use single quotes in ``template example``...
Yuya Nishihara -
r34659:dbe1f511 default
parent child Browse files
Show More
@@ -1,215 +1,215
1 1 Mercurial allows you to customize output of commands through
2 2 templates. You can either pass in a template or select an existing
3 3 template-style from the command line, via the --template option.
4 4
5 5 You can customize output for any "log-like" command: log,
6 6 outgoing, incoming, tip, parents, and heads.
7 7
8 8 Some built-in styles are packaged with Mercurial. These can be listed
9 9 with :hg:`log --template list`. Example usage::
10 10
11 11 $ hg log -r1.0::1.1 --template changelog
12 12
13 13 A template is a piece of text, with markup to invoke variable
14 14 expansion::
15 15
16 16 $ hg log -r1 --template "{node}\n"
17 17 b56ce7b07c52de7d5fd79fb89701ea538af65746
18 18
19 19 Keywords
20 20 ========
21 21
22 22 Strings in curly braces are called keywords. The availability of
23 23 keywords depends on the exact context of the templater. These
24 24 keywords are usually available for templating a log-like command:
25 25
26 26 .. keywordsmarker
27 27
28 28 The "date" keyword does not produce human-readable output. If you
29 29 want to use a date in your output, you can use a filter to process
30 30 it. Filters are functions which return a string based on the input
31 31 variable. Be sure to use the stringify filter first when you're
32 32 applying a string-input filter to a list-like input variable.
33 33 You can also use a chain of filters to get the desired output::
34 34
35 35 $ hg tip --template "{date|isodate}\n"
36 36 2008-08-21 18:22 +0000
37 37
38 38 Filters
39 39 =======
40 40
41 41 List of filters:
42 42
43 43 .. filtersmarker
44 44
45 45 Note that a filter is nothing more than a function call, i.e.
46 46 ``expr|filter`` is equivalent to ``filter(expr)``.
47 47
48 48 Functions
49 49 =========
50 50
51 51 In addition to filters, there are some basic built-in functions:
52 52
53 53 .. functionsmarker
54 54
55 55 Operators
56 56 =========
57 57
58 58 We provide a limited set of infix arithmetic operations on integers::
59 59
60 60 + for addition
61 61 - for subtraction
62 62 * for multiplication
63 63 / for floor division (division rounded to integer nearest -infinity)
64 64
65 65 Division fulfills the law x = x / y + mod(x, y).
66 66
67 67 Also, for any expression that returns a list, there is a list operator::
68 68
69 69 expr % "{template}"
70 70
71 71 As seen in the above example, ``{template}`` is interpreted as a template.
72 72 To prevent it from being interpreted, you can use an escape character ``\{``
73 73 or a raw string prefix, ``r'...'``.
74 74
75 75 The dot operator can be used as a shorthand for accessing a sub item:
76 76
77 - ``expr.member`` is roughly equivalent to ``expr % "{member}"`` if ``expr``
77 - ``expr.member`` is roughly equivalent to ``expr % '{member}'`` if ``expr``
78 78 returns a non-list/dict. The returned value is not stringified.
79 - ``dict.key`` is identical to ``get(dict, "key")``.
79 - ``dict.key`` is identical to ``get(dict, 'key')``.
80 80
81 81 Aliases
82 82 =======
83 83
84 84 New keywords and functions can be defined in the ``templatealias`` section of
85 85 a Mercurial configuration file::
86 86
87 87 <alias> = <definition>
88 88
89 89 Arguments of the form `a1`, `a2`, etc. are substituted from the alias into
90 90 the definition.
91 91
92 92 For example,
93 93
94 94 ::
95 95
96 96 [templatealias]
97 97 r = rev
98 98 rn = "{r}:{node|short}"
99 99 leftpad(s, w) = pad(s, w, ' ', True)
100 100
101 101 defines two symbol aliases, ``r`` and ``rn``, and a function alias
102 102 ``leftpad()``.
103 103
104 104 It's also possible to specify complete template strings, using the
105 105 ``templates`` section. The syntax used is the general template string syntax.
106 106
107 107 For example,
108 108
109 109 ::
110 110
111 111 [templates]
112 112 nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
113 113
114 114 defines a template, ``nodedate``, which can be called like::
115 115
116 116 $ hg log -r . -Tnodedate
117 117
118 118 A template defined in ``templates`` section can also be referenced from
119 119 another template::
120 120
121 121 $ hg log -r . -T "{rev} {nodedate}"
122 122
123 123 but be aware that the keywords cannot be overridden by templates. For example,
124 124 a template defined as ``templates.rev`` cannot be referenced as ``{rev}``.
125 125
126 126 A template defined in ``templates`` section may have sub templates which
127 127 are inserted before/after/between items::
128 128
129 129 [templates]
130 130 myjson = ' {dict(rev, node|short)|json}'
131 131 myjson:docheader = '\{\n'
132 132 myjson:docfooter = '\n}\n'
133 133 myjson:separator = ',\n'
134 134
135 135 Examples
136 136 ========
137 137
138 138 Some sample command line templates:
139 139
140 140 - Format lists, e.g. files::
141 141
142 142 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
143 143
144 144 - Join the list of files with a ", "::
145 145
146 146 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
147 147
148 148 - Join the list of files ending with ".py" with a ", "::
149 149
150 150 $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
151 151
152 152 - Separate non-empty arguments by a " "::
153 153
154 154 $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
155 155
156 156 - Modify each line of a commit description::
157 157
158 158 $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
159 159
160 160 - Format date::
161 161
162 162 $ hg log -r 0 --template "{date(date, '%Y')}\n"
163 163
164 164 - Display date in UTC::
165 165
166 166 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
167 167
168 168 - Output the description set to a fill-width of 30::
169 169
170 170 $ hg log -r 0 --template "{fill(desc, 30)}"
171 171
172 172 - Use a conditional to test for the default branch::
173 173
174 174 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
175 175 'on branch {branch}')}\n"
176 176
177 177 - Append a newline if not empty::
178 178
179 179 $ hg tip --template "{if(author, '{author}\n')}"
180 180
181 181 - Label the output for use with the color extension::
182 182
183 183 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
184 184
185 185 - Invert the firstline filter, i.e. everything but the first line::
186 186
187 187 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
188 188
189 189 - Display the contents of the 'extra' field, one per line::
190 190
191 191 $ hg log -r 0 --template "{join(extras, '\n')}\n"
192 192
193 193 - Mark the active bookmark with '*'::
194 194
195 195 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
196 196
197 197 - Find the previous release candidate tag, the distance and changes since the tag::
198 198
199 199 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
200 200
201 201 - Mark the working copy parent with '@'::
202 202
203 203 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
204 204
205 205 - Show details of parent revisions::
206 206
207 207 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
208 208
209 209 - Show only commit descriptions that start with "template"::
210 210
211 211 $ hg log --template "{startswith('template', firstline(desc))}\n"
212 212
213 213 - Print the first word of each line of a commit message::
214 214
215 215 $ hg log --template "{word(0, desc)}\n"
General Comments 0
You need to be logged in to leave comments. Login now