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