##// END OF EJS Templates
help: add ifcontains, revset, and shortest to template help...
Durham Goode -
r20531:01a75c9d default
parent child Browse files
Show More
@@ -1,108 +1,122
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 from the command
2 templates. You can either pass in a template from the command
3 line, via the --template option, or select an existing
3 line, via the --template option, or select an existing
4 template-style (--style).
4 template-style (--style).
5
5
6 You can customize output for any "log-like" command: log,
6 You can customize output for any "log-like" command: log,
7 outgoing, incoming, tip, parents, heads and glog.
7 outgoing, incoming, tip, parents, heads and glog.
8
8
9 Five styles are packaged with Mercurial: default (the style used
9 Five styles are packaged with Mercurial: default (the style used
10 when no explicit preference is passed), compact, changelog, phases
10 when no explicit preference is passed), compact, changelog, phases
11 and xml.
11 and xml.
12 Usage::
12 Usage::
13
13
14 $ hg log -r1 --style changelog
14 $ hg log -r1 --style changelog
15
15
16 A template is a piece of text, with markup to invoke variable
16 A template is a piece of text, with markup to invoke variable
17 expansion::
17 expansion::
18
18
19 $ hg log -r1 --template "{node}\n"
19 $ hg log -r1 --template "{node}\n"
20 b56ce7b07c52de7d5fd79fb89701ea538af65746
20 b56ce7b07c52de7d5fd79fb89701ea538af65746
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 List of filters:
38 List of filters:
39
39
40 .. filtersmarker
40 .. filtersmarker
41
41
42 Note that a filter is nothing more than a function call, i.e.
42 Note that a filter is nothing more than a function call, i.e.
43 ``expr|filter`` is equivalent to ``filter(expr)``.
43 ``expr|filter`` is equivalent to ``filter(expr)``.
44
44
45 In addition to filters, there are some basic built-in functions:
45 In addition to filters, there are some basic built-in functions:
46
46
47 - date(date[, fmt])
47 - date(date[, fmt])
48
48
49 - fill(text[, width])
49 - fill(text[, width])
50
50
51 - get(dict, key)
51 - get(dict, key)
52
52
53 - if(expr, then[, else])
53 - if(expr, then[, else])
54
54
55 - ifcontains(expr, expr, then[, else])
56
55 - ifeq(expr, expr, then[, else])
57 - ifeq(expr, expr, then[, else])
56
58
57 - join(list, sep)
59 - join(list, sep)
58
60
59 - label(label, expr)
61 - label(label, expr)
60
62
63 - revset(query[, formatargs])
64
61 - rstdoc(text, style)
65 - rstdoc(text, style)
62
66
67 - shortest(node)
68
63 - strip(text[, chars])
69 - strip(text[, chars])
64
70
65 - sub(pat, repl, expr)
71 - sub(pat, repl, expr)
66
72
67 Also, for any expression that returns a list, there is a list operator:
73 Also, for any expression that returns a list, there is a list operator:
68
74
69 - expr % "{template}"
75 - expr % "{template}"
70
76
71 Some sample command line templates:
77 Some sample command line templates:
72
78
73 - Format lists, e.g. files::
79 - Format lists, e.g. files::
74
80
75 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
81 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
76
82
77 - Join the list of files with a ", "::
83 - Join the list of files with a ", "::
78
84
79 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
85 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
80
86
81 - Format date::
87 - Format date::
82
88
83 $ hg log -r 0 --template "{date(date, '%Y')}\n"
89 $ hg log -r 0 --template "{date(date, '%Y')}\n"
84
90
85 - Output the description set to a fill-width of 30::
91 - Output the description set to a fill-width of 30::
86
92
87 $ hg log -r 0 --template "{fill(desc, '30')}"
93 $ hg log -r 0 --template "{fill(desc, '30')}"
88
94
89 - Use a conditional to test for the default branch::
95 - Use a conditional to test for the default branch::
90
96
91 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
97 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
92 'on branch {branch}')}\n"
98 'on branch {branch}')}\n"
93
99
94 - Append a newline if not empty::
100 - Append a newline if not empty::
95
101
96 $ hg tip --template "{if(author, '{author}\n')}"
102 $ hg tip --template "{if(author, '{author}\n')}"
97
103
98 - Label the output for use with the color extension::
104 - Label the output for use with the color extension::
99
105
100 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
106 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
101
107
102 - Invert the firstline filter, i.e. everything but the first line::
108 - Invert the firstline filter, i.e. everything but the first line::
103
109
104 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
110 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
105
111
106 - Display the contents of the 'extra' field, one per line::
112 - Display the contents of the 'extra' field, one per line::
107
113
108 $ hg log -r 0 --template "{join(extras, '\n')}\n"
114 $ hg log -r 0 --template "{join(extras, '\n')}\n"
115
116 - Mark the current bookmark with '*'::
117
118 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, current, \"*\")} '}\n"
119
120 - Mark the working copy parent with '@'::
121
122 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
General Comments 0
You need to be logged in to leave comments. Login now