author | Yuya Nishihara <yuya@tcha.org> |
Tue, 19 May 2015 23:29:20 +0900 | |
changeset 25225 | 57fae767c52b |
parent 25004 | e264d4c9629b |
child 25348 | f26efa4f0eff |
permissions | -rw-r--r-- |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
1 |
Mercurial allows you to customize output of commands through |
21943
8534e670f4ee
help: use --template to specify existing style
Yuya Nishihara <yuya@tcha.org>
parents:
21846
diff
changeset
|
2 |
templates. You can either pass in a template or select an existing |
8534e670f4ee
help: use --template to specify existing style
Yuya Nishihara <yuya@tcha.org>
parents:
21846
diff
changeset
|
3 |
template-style from the command line, via the --template option. |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
4 |
|
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
5 |
You can customize output for any "log-like" command: log, |
21945
d603e7333281
help: drop reference to glog in templates topic
Matt Mackall <mpm@selenic.com>
parents:
21943
diff
changeset
|
6 |
outgoing, incoming, tip, parents, and heads. |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
7 |
|
21946
868e2cea3ea0
help: mention '-T list' in templater topic
Matt Mackall <mpm@selenic.com>
parents:
21945
diff
changeset
|
8 |
Some built-in styles are packaged with Mercurial. These can be listed |
868e2cea3ea0
help: mention '-T list' in templater topic
Matt Mackall <mpm@selenic.com>
parents:
21945
diff
changeset
|
9 |
with :hg:`log --template list`. Example usage:: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
10 |
|
21946
868e2cea3ea0
help: mention '-T list' in templater topic
Matt Mackall <mpm@selenic.com>
parents:
21945
diff
changeset
|
11 |
$ hg log -r1.0::1.1 --template changelog |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
12 |
|
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
13 |
A template is a piece of text, with markup to invoke variable |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
14 |
expansion:: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
15 |
|
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
16 |
$ hg log -r1 --template "{node}\n" |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
17 |
b56ce7b07c52de7d5fd79fb89701ea538af65746 |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
18 |
|
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
19 |
Strings in curly braces are called keywords. The availability of |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
20 |
keywords depends on the exact context of the templater. These |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
21 |
keywords are usually available for templating a log-like command: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
22 |
|
13585
2e80d495592a
templates: generate keyword help dynamically
Patrick Mezard <pmezard@gmail.com>
parents:
13498
diff
changeset
|
23 |
.. keywordsmarker |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
24 |
|
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
25 |
The "date" keyword does not produce human-readable output. If you |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
26 |
want to use a date in your output, you can use a filter to process |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
27 |
it. Filters are functions which return a string based on the input |
10759
9f6e30a89f11
help: point out need for stringification
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
10066
diff
changeset
|
28 |
variable. Be sure to use the stringify filter first when you're |
9f6e30a89f11
help: point out need for stringification
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
10066
diff
changeset
|
29 |
applying a string-input filter to a list-like input variable. |
9f6e30a89f11
help: point out need for stringification
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
10066
diff
changeset
|
30 |
You can also use a chain of filters to get the desired output:: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
31 |
|
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
32 |
$ hg tip --template "{date|isodate}\n" |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
33 |
2008-08-21 18:22 +0000 |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
34 |
|
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
35 |
List of filters: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
36 |
|
13591
264f292a0c6f
templatefilters: move doc from templates.txt to docstrings
Patrick Mezard <pmezard@gmail.com>
parents:
13585
diff
changeset
|
37 |
.. filtersmarker |
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
38 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
39 |
Note that a filter is nothing more than a function call, i.e. |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
40 |
``expr|filter`` is equivalent to ``filter(expr)``. |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
41 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
42 |
In addition to filters, there are some basic built-in functions: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
43 |
|
24587
76c0b4cfa039
help: populate template functions via docstrings
Gregory Szorc <gregory.szorc@gmail.com>
parents:
22434
diff
changeset
|
44 |
.. functionsmarker |
21846
8f23f8096606
templater: introduce word function
Ryan McElroy <rmcelroy@fb.com>
parents:
21821
diff
changeset
|
45 |
|
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
46 |
Also, for any expression that returns a list, there is a list operator: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
47 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
48 |
- expr % "{template}" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
49 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
50 |
Some sample command line templates: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
51 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
52 |
- Format lists, e.g. files:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
53 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
54 |
$ hg log -r 0 --template "files:\n{files % ' {file}\n'}" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
55 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
56 |
- Join the list of files with a ", ":: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
57 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
58 |
$ hg log -r 0 --template "files: {join(files, ', ')}\n" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
59 |
|
21820
cce404b0c918
templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents:
20531
diff
changeset
|
60 |
- Modify each line of a commit description:: |
cce404b0c918
templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents:
20531
diff
changeset
|
61 |
|
cce404b0c918
templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents:
20531
diff
changeset
|
62 |
$ hg log --template "{splitlines(desc) % '**** {line}\n'}" |
cce404b0c918
templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents:
20531
diff
changeset
|
63 |
|
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
64 |
- Format date:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
65 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
66 |
$ hg log -r 0 --template "{date(date, '%Y')}\n" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
67 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
68 |
- Output the description set to a fill-width of 30:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
69 |
|
25004
e264d4c9629b
help: rewrite template examples to use integer literals where appropriate
Yuya Nishihara <yuya@tcha.org>
parents:
24587
diff
changeset
|
70 |
$ hg log -r 0 --template "{fill(desc, 30)}" |
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
71 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
72 |
- Use a conditional to test for the default branch:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
73 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
74 |
$ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch', |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
75 |
'on branch {branch}')}\n" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
76 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
77 |
- Append a newline if not empty:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
78 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
79 |
$ hg tip --template "{if(author, '{author}\n')}" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
80 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
81 |
- Label the output for use with the color extension:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
82 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
83 |
$ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
84 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
85 |
- Invert the firstline filter, i.e. everything but the first line:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
86 |
|
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
87 |
$ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n" |
20016
f4b3bdc3019e
help: adding example 'extras' printing to 'hg help templates'
Matthew Turk <matthewturk@gmail.com>
parents:
19390
diff
changeset
|
88 |
|
f4b3bdc3019e
help: adding example 'extras' printing to 'hg help templates'
Matthew Turk <matthewturk@gmail.com>
parents:
19390
diff
changeset
|
89 |
- Display the contents of the 'extra' field, one per line:: |
f4b3bdc3019e
help: adding example 'extras' printing to 'hg help templates'
Matthew Turk <matthewturk@gmail.com>
parents:
19390
diff
changeset
|
90 |
|
20170
574f3b6e0e8b
help: fix formatting of template example
Steve Hoelzer <shoelzer@gmail.com>
parents:
20016
diff
changeset
|
91 |
$ hg log -r 0 --template "{join(extras, '\n')}\n" |
20531
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
92 |
|
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
93 |
- Mark the current bookmark with '*':: |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
94 |
|
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
95 |
$ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, current, \"*\")} '}\n" |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
96 |
|
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
97 |
- Mark the working copy parent with '@':: |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
98 |
|
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
99 |
$ hg log --template "{ifcontains(rev, revset('.'), '@')}\n" |
21821
4a445dc5abff
templater: introduce startswith function
Ryan McElroy <rmcelroy@fb.com>
parents:
21820
diff
changeset
|
100 |
|
4a445dc5abff
templater: introduce startswith function
Ryan McElroy <rmcelroy@fb.com>
parents:
21820
diff
changeset
|
101 |
- Show only commit descriptions that start with "template":: |
4a445dc5abff
templater: introduce startswith function
Ryan McElroy <rmcelroy@fb.com>
parents:
21820
diff
changeset
|
102 |
|
4a445dc5abff
templater: introduce startswith function
Ryan McElroy <rmcelroy@fb.com>
parents:
21820
diff
changeset
|
103 |
$ hg log --template "{startswith(\"template\", firstline(desc))}\n" |
21846
8f23f8096606
templater: introduce word function
Ryan McElroy <rmcelroy@fb.com>
parents:
21821
diff
changeset
|
104 |
|
8f23f8096606
templater: introduce word function
Ryan McElroy <rmcelroy@fb.com>
parents:
21821
diff
changeset
|
105 |
- Print the first word of each line of a commit message:: |
8f23f8096606
templater: introduce word function
Ryan McElroy <rmcelroy@fb.com>
parents:
21821
diff
changeset
|
106 |
|
25004
e264d4c9629b
help: rewrite template examples to use integer literals where appropriate
Yuya Nishihara <yuya@tcha.org>
parents:
24587
diff
changeset
|
107 |
$ hg log --template "{word(0, desc)}\n" |