Mercurial > hg
annotate mercurial/help/templates.txt @ 28238:b57d45ec33b2
test: update test-bundle2-format.t comment
Now that bundle2 is used by default for all exchanges, this comment is obviously
out of date. Having deep testing of the API and expected behavior of the format
and its processing is still valuable, so the comment is updated.
author | Pierre-Yves David <pierre-yves.david@fb.com> |
---|---|
date | Thu, 25 Feb 2016 10:34:31 +0100 |
parents | 6db47740e681 |
children | d813132ea361 |
rev | line source |
---|---|
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 |
28040
6db47740e681
help: update template examples to use reST literal syntax
Yuya Nishihara <yuya@tcha.org>
parents:
26485
diff
changeset
|
46 Also, for any expression that returns a list, there is a list operator:: |
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
47 |
28040
6db47740e681
help: update template examples to use reST literal syntax
Yuya Nishihara <yuya@tcha.org>
parents:
26485
diff
changeset
|
48 expr % "{template}" |
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
49 |
28040
6db47740e681
help: update template examples to use reST literal syntax
Yuya Nishihara <yuya@tcha.org>
parents:
26485
diff
changeset
|
50 As seen in the above example, ``{template}`` is interpreted as a template. |
6db47740e681
help: update template examples to use reST literal syntax
Yuya Nishihara <yuya@tcha.org>
parents:
26485
diff
changeset
|
51 To prevent it from being interpreted, you can use an escape character ``\{`` |
6db47740e681
help: update template examples to use reST literal syntax
Yuya Nishihara <yuya@tcha.org>
parents:
26485
diff
changeset
|
52 or a raw string prefix, ``r'...'``. |
25596
c1975809a6b5
templater: take any string literals as template, but not for rawstring (BC)
Yuya Nishihara <yuya@tcha.org>
parents:
25348
diff
changeset
|
53 |
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
54 Some sample command line templates: |
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 - Format lists, e.g. files:: |
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:\n{files % ' {file}\n'}" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
59 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
60 - 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
|
61 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
62 $ 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
|
63 |
21820
cce404b0c918
templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents:
20531
diff
changeset
|
64 - Modify each line of a commit description:: |
cce404b0c918
templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents:
20531
diff
changeset
|
65 |
cce404b0c918
templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents:
20531
diff
changeset
|
66 $ hg log --template "{splitlines(desc) % '**** {line}\n'}" |
cce404b0c918
templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents:
20531
diff
changeset
|
67 |
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
68 - Format date:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
69 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
70 $ 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
|
71 |
26128
51f6940d3b4f
templater: add optional timezone argument to localdate()
Yuya Nishihara <yuya@tcha.org>
parents:
25786
diff
changeset
|
72 - Display date in UTC:: |
51f6940d3b4f
templater: add optional timezone argument to localdate()
Yuya Nishihara <yuya@tcha.org>
parents:
25786
diff
changeset
|
73 |
51f6940d3b4f
templater: add optional timezone argument to localdate()
Yuya Nishihara <yuya@tcha.org>
parents:
25786
diff
changeset
|
74 $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n" |
51f6940d3b4f
templater: add optional timezone argument to localdate()
Yuya Nishihara <yuya@tcha.org>
parents:
25786
diff
changeset
|
75 |
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
76 - 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
|
77 |
25004
e264d4c9629b
help: rewrite template examples to use integer literals where appropriate
Yuya Nishihara <yuya@tcha.org>
parents:
24587
diff
changeset
|
78 $ 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
|
79 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
80 - 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
|
81 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
82 $ 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
|
83 'on branch {branch}')}\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 - 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
|
86 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
87 $ 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
|
88 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
89 - 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
|
90 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
91 $ 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
|
92 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
93 - 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
|
94 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
95 $ 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
|
96 |
f4b3bdc3019e
help: adding example 'extras' printing to 'hg help templates'
Matthew Turk <matthewturk@gmail.com>
parents:
19390
diff
changeset
|
97 - 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
|
98 |
20170
574f3b6e0e8b
help: fix formatting of template example
Steve Hoelzer <shoelzer@gmail.com>
parents:
20016
diff
changeset
|
99 $ 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
|
100 |
25348
f26efa4f0eff
templatekw: introduce active subkeyword from bookmarks keyword
Ryan McElroy <rmcelroy@fb.com>
parents:
25004
diff
changeset
|
101 - Mark the active bookmark with '*':: |
20531
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
102 |
25786
35fa7c77c754
help: rewrite template examples to not use shell escaping
Yuya Nishihara <yuya@tcha.org>
parents:
25596
diff
changeset
|
103 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n" |
20531
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
104 |
26485
43bf9471fae9
templater: introduce {latesttag()} function to match a pattern (issue4184)
Matt Harbison <matt_harbison@yahoo.com>
parents:
26234
diff
changeset
|
105 - Find the previous release candidate tag, the distance and changes since the tag:: |
43bf9471fae9
templater: introduce {latesttag()} function to match a pattern (issue4184)
Matt Harbison <matt_harbison@yahoo.com>
parents:
26234
diff
changeset
|
106 |
43bf9471fae9
templater: introduce {latesttag()} function to match a pattern (issue4184)
Matt Harbison <matt_harbison@yahoo.com>
parents:
26234
diff
changeset
|
107 $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n" |
43bf9471fae9
templater: introduce {latesttag()} function to match a pattern (issue4184)
Matt Harbison <matt_harbison@yahoo.com>
parents:
26234
diff
changeset
|
108 |
20531
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
109 - 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
|
110 |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
111 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n" |
21821
4a445dc5abff
templater: introduce startswith function
Ryan McElroy <rmcelroy@fb.com>
parents:
21820
diff
changeset
|
112 |
26234
e4609ec959f8
templater: switch ctx of list expression to rev of revset() (BC)
Yuya Nishihara <yuya@tcha.org>
parents:
26128
diff
changeset
|
113 - Show details of parent revisions:: |
e4609ec959f8
templater: switch ctx of list expression to rev of revset() (BC)
Yuya Nishihara <yuya@tcha.org>
parents:
26128
diff
changeset
|
114 |
e4609ec959f8
templater: switch ctx of list expression to rev of revset() (BC)
Yuya Nishihara <yuya@tcha.org>
parents:
26128
diff
changeset
|
115 $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}" |
e4609ec959f8
templater: switch ctx of list expression to rev of revset() (BC)
Yuya Nishihara <yuya@tcha.org>
parents:
26128
diff
changeset
|
116 |
21821
4a445dc5abff
templater: introduce startswith function
Ryan McElroy <rmcelroy@fb.com>
parents:
21820
diff
changeset
|
117 - Show only commit descriptions that start with "template":: |
4a445dc5abff
templater: introduce startswith function
Ryan McElroy <rmcelroy@fb.com>
parents:
21820
diff
changeset
|
118 |
25786
35fa7c77c754
help: rewrite template examples to not use shell escaping
Yuya Nishihara <yuya@tcha.org>
parents:
25596
diff
changeset
|
119 $ hg log --template "{startswith('template', firstline(desc))}\n" |
21846
8f23f8096606
templater: introduce word function
Ryan McElroy <rmcelroy@fb.com>
parents:
21821
diff
changeset
|
120 |
8f23f8096606
templater: introduce word function
Ryan McElroy <rmcelroy@fb.com>
parents:
21821
diff
changeset
|
121 - 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
|
122 |
25004
e264d4c9629b
help: rewrite template examples to use integer literals where appropriate
Yuya Nishihara <yuya@tcha.org>
parents:
24587
diff
changeset
|
123 $ hg log --template "{word(0, desc)}\n" |