##// END OF EJS Templates
help: add documentation for new template functions
Sean Farley -
r18465:3aa8b4b3 stable
parent child Browse files
Show More
@@ -1,40 +1,98 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 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 Four styles are packaged with Mercurial: default (the style used
9 Four styles are packaged with Mercurial: default (the style used
10 when no explicit preference is passed), compact, changelog,
10 when no explicit preference is passed), compact, changelog,
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
42 Note that a filter is nothing more than a function call, i.e.
43 ``expr|filter`` is equivalent to ``filter(expr)``.
44
45 In addition to filters, there are some basic built-in functions:
46
47 - if(expr, then[, else])
48
49 - ifeq(expr, expr, then[, else])
50
51 - sub(pat, repl, expr)
52
53 - join(list, sep)
54
55 - label(label, expr)
56
57 - date(date[, fmt])
58
59 - fill(text[, width])
60
61 Also, for any expression that returns a list, there is a list operator:
62
63 - expr % "{template}"
64
65 Some sample command line templates:
66
67 - Format lists, e.g. files::
68
69 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
70
71 - Join the list of files with a ", "::
72
73 $ hg log -r 0 --template "files: {join(files, ', ')}\n"
74
75 - Format date::
76
77 $ hg log -r 0 --template "{date(date, '%Y')}\n"
78
79 - Output the description set to a fill-width of 30::
80
81 $ hg log -r 0 --template "{fill(desc, '30')}"
82
83 - Use a conditional to test for the default branch::
84
85 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
86 'on branch {branch}')}\n"
87
88 - Append a newline if not empty::
89
90 $ hg tip --template "{if(author, '{author}\n')}"
91
92 - Label the output for use with the color extension::
93
94 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
95
96 - Invert the firstline filter, i.e. everything but the first line::
97
98 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
General Comments 0
You need to be logged in to leave comments. Login now