mercurial/helptext/templates.txt
author Pierre-Yves David <pierre-yves.david@octobus.net>
Fri, 16 Jul 2021 17:32:40 +0200
changeset 47904 822c67420c77
parent 43632 2e017696181f
permissions -rw-r--r--
dirstatemap: use the default code to handle "merged" case This simplify the conditionnal a bit since most of it is handled by the common code. Differential Revision: https://phab.mercurial-scm.org/D11329
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
30730
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    19
Keywords
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    20
========
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    21
9540
cad36e496640 help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents: 9539
diff changeset
    22
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
    23
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
    24
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
    25
13585
2e80d495592a templates: generate keyword help dynamically
Patrick Mezard <pmezard@gmail.com>
parents: 13498
diff changeset
    26
.. keywordsmarker
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff changeset
    27
9540
cad36e496640 help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents: 9539
diff changeset
    28
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
    29
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
    30
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
    31
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
    32
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
    33
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
    34
9540
cad36e496640 help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents: 9539
diff changeset
    35
   $ hg tip --template "{date|isodate}\n"
cad36e496640 help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents: 9539
diff changeset
    36
   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
    37
30730
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    38
Filters
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    39
=======
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    40
9540
cad36e496640 help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents: 9539
diff changeset
    41
List of filters:
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff changeset
    42
13591
264f292a0c6f templatefilters: move doc from templates.txt to docstrings
Patrick Mezard <pmezard@gmail.com>
parents: 13585
diff changeset
    43
.. filtersmarker
18465
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
    44
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
    45
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
    46
``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
    47
30730
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    48
Functions
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    49
=========
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    50
18465
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
    51
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
    52
24587
76c0b4cfa039 help: populate template functions via docstrings
Gregory Szorc <gregory.szorc@gmail.com>
parents: 22434
diff changeset
    53
.. functionsmarker
21846
8f23f8096606 templater: introduce word function
Ryan McElroy <rmcelroy@fb.com>
parents: 21821
diff changeset
    54
30731
b8a188a6f191 help: merge the various operator sections of revsets, filesets and templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30730
diff changeset
    55
Operators
b8a188a6f191 help: merge the various operator sections of revsets, filesets and templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30730
diff changeset
    56
=========
30730
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    57
30115
8e42dfde93d1 templater: provide arithmetic operations on integers
Simon Farnsworth <simonfar@fb.com>
parents: 30008
diff changeset
    58
We provide a limited set of infix arithmetic operations on integers::
8e42dfde93d1 templater: provide arithmetic operations on integers
Simon Farnsworth <simonfar@fb.com>
parents: 30008
diff changeset
    59
8e42dfde93d1 templater: provide arithmetic operations on integers
Simon Farnsworth <simonfar@fb.com>
parents: 30008
diff changeset
    60
  + for addition
8e42dfde93d1 templater: provide arithmetic operations on integers
Simon Farnsworth <simonfar@fb.com>
parents: 30008
diff changeset
    61
  - for subtraction
8e42dfde93d1 templater: provide arithmetic operations on integers
Simon Farnsworth <simonfar@fb.com>
parents: 30008
diff changeset
    62
  * for multiplication
8e42dfde93d1 templater: provide arithmetic operations on integers
Simon Farnsworth <simonfar@fb.com>
parents: 30008
diff changeset
    63
  / for floor division (division rounded to integer nearest -infinity)
8e42dfde93d1 templater: provide arithmetic operations on integers
Simon Farnsworth <simonfar@fb.com>
parents: 30008
diff changeset
    64
32139
de86a6872d06 help: spelling fixes
Matt Harbison <matt_harbison@yahoo.com>
parents: 30731
diff changeset
    65
Division fulfills the law x = x / y + mod(x, y).
30115
8e42dfde93d1 templater: provide arithmetic operations on integers
Simon Farnsworth <simonfar@fb.com>
parents: 30008
diff changeset
    66
28040
6db47740e681 help: update template examples to use reST literal syntax
Yuya Nishihara <yuya@tcha.org>
parents: 26485
diff changeset
    67
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
    68
28040
6db47740e681 help: update template examples to use reST literal syntax
Yuya Nishihara <yuya@tcha.org>
parents: 26485
diff changeset
    69
    expr % "{template}"
18465
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
    70
28040
6db47740e681 help: update template examples to use reST literal syntax
Yuya Nishihara <yuya@tcha.org>
parents: 26485
diff changeset
    71
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
    72
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
    73
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
    74
34535
78590585c0db templater: add dot operator to easily access a sub item
Yuya Nishihara <yuya@tcha.org>
parents: 32952
diff changeset
    75
The dot operator can be used as a shorthand for accessing a sub item:
78590585c0db templater: add dot operator to easily access a sub item
Yuya Nishihara <yuya@tcha.org>
parents: 32952
diff changeset
    76
34658
dbe1f5118864 help: use single quotes in ``template example``
Yuya Nishihara <yuya@tcha.org>
parents: 34536
diff changeset
    77
- ``expr.member`` is roughly equivalent to ``expr % '{member}'`` if ``expr``
34535
78590585c0db templater: add dot operator to easily access a sub item
Yuya Nishihara <yuya@tcha.org>
parents: 32952
diff changeset
    78
  returns a non-list/dict. The returned value is not stringified.
34658
dbe1f5118864 help: use single quotes in ``template example``
Yuya Nishihara <yuya@tcha.org>
parents: 34536
diff changeset
    79
- ``dict.key`` is identical to ``get(dict, 'key')``.
34535
78590585c0db templater: add dot operator to easily access a sub item
Yuya Nishihara <yuya@tcha.org>
parents: 32952
diff changeset
    80
30730
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    81
Aliases
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    82
=======
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
    83
28957
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    84
New keywords and functions can be defined in the ``templatealias`` section of
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    85
a Mercurial configuration file::
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    86
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    87
  <alias> = <definition>
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    88
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    89
Arguments of the form `a1`, `a2`, etc. are substituted from the alias into
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    90
the definition.
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    91
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    92
For example,
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    93
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    94
::
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    95
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    96
  [templatealias]
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    97
  r = rev
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    98
  rn = "{r}:{node|short}"
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
    99
  leftpad(s, w) = pad(s, w, ' ', True)
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
   100
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
   101
defines two symbol aliases, ``r`` and ``rn``, and a function alias
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
   102
``leftpad()``.
d813132ea361 templater: load and expand aliases by template engine (API) (issue4842)
Yuya Nishihara <yuya@tcha.org>
parents: 28040
diff changeset
   103
29717
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   104
It's also possible to specify complete template strings, using the
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   105
``templates`` section. The syntax used is the general template string syntax.
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   106
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   107
For example,
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   108
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   109
::
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   110
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   111
  [templates]
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   112
  nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   113
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   114
defines a template, ``nodedate``, which can be called like::
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   115
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   116
  $ hg log -r . -Tnodedate
a12d13eac513 help: add example of '[templates]' usage
Mathias De Maré <mathias.demare@gmail.com>
parents: 29085
diff changeset
   117
32875
c8f2cf18b82e formatter: load templates section like a map file
Yuya Nishihara <yuya@tcha.org>
parents: 32139
diff changeset
   118
A template defined in ``templates`` section can also be referenced from
c8f2cf18b82e formatter: load templates section like a map file
Yuya Nishihara <yuya@tcha.org>
parents: 32139
diff changeset
   119
another template::
c8f2cf18b82e formatter: load templates section like a map file
Yuya Nishihara <yuya@tcha.org>
parents: 32139
diff changeset
   120
c8f2cf18b82e formatter: load templates section like a map file
Yuya Nishihara <yuya@tcha.org>
parents: 32139
diff changeset
   121
  $ hg log -r . -T "{rev} {nodedate}"
c8f2cf18b82e formatter: load templates section like a map file
Yuya Nishihara <yuya@tcha.org>
parents: 32139
diff changeset
   122
c8f2cf18b82e formatter: load templates section like a map file
Yuya Nishihara <yuya@tcha.org>
parents: 32139
diff changeset
   123
but be aware that the keywords cannot be overridden by templates. For example,
c8f2cf18b82e formatter: load templates section like a map file
Yuya Nishihara <yuya@tcha.org>
parents: 32139
diff changeset
   124
a template defined as ``templates.rev`` cannot be referenced as ``{rev}``.
c8f2cf18b82e formatter: load templates section like a map file
Yuya Nishihara <yuya@tcha.org>
parents: 32139
diff changeset
   125
32952
61b60b28c381 formatter: add support for parts map of [templates] section
Yuya Nishihara <yuya@tcha.org>
parents: 32875
diff changeset
   126
A template defined in ``templates`` section may have sub templates which
61b60b28c381 formatter: add support for parts map of [templates] section
Yuya Nishihara <yuya@tcha.org>
parents: 32875
diff changeset
   127
are inserted before/after/between items::
61b60b28c381 formatter: add support for parts map of [templates] section
Yuya Nishihara <yuya@tcha.org>
parents: 32875
diff changeset
   128
61b60b28c381 formatter: add support for parts map of [templates] section
Yuya Nishihara <yuya@tcha.org>
parents: 32875
diff changeset
   129
  [templates]
61b60b28c381 formatter: add support for parts map of [templates] section
Yuya Nishihara <yuya@tcha.org>
parents: 32875
diff changeset
   130
  myjson = ' {dict(rev, node|short)|json}'
61b60b28c381 formatter: add support for parts map of [templates] section
Yuya Nishihara <yuya@tcha.org>
parents: 32875
diff changeset
   131
  myjson:docheader = '\{\n'
61b60b28c381 formatter: add support for parts map of [templates] section
Yuya Nishihara <yuya@tcha.org>
parents: 32875
diff changeset
   132
  myjson:docfooter = '\n}\n'
61b60b28c381 formatter: add support for parts map of [templates] section
Yuya Nishihara <yuya@tcha.org>
parents: 32875
diff changeset
   133
  myjson:separator = ',\n'
61b60b28c381 formatter: add support for parts map of [templates] section
Yuya Nishihara <yuya@tcha.org>
parents: 32875
diff changeset
   134
30730
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
   135
Examples
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
   136
========
107014f4848b help: apply the section headings from revsets to templates
Matt Harbison <matt_harbison@yahoo.com>
parents: 30115
diff changeset
   137
18465
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   138
Some sample command line templates:
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   139
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   140
- Format lists, e.g. files::
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   141
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   142
   $ 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
   143
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   144
- 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
   145
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   146
   $ 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
   147
30008
e83f89d3b1f7 templates: add built-in files() function
Hannes Oldenburg <hannes.christian.oldenburg@gmail.com>
parents: 29717
diff changeset
   148
- Join the list of files ending with ".py" with a ", "::
e83f89d3b1f7 templates: add built-in files() function
Hannes Oldenburg <hannes.christian.oldenburg@gmail.com>
parents: 29717
diff changeset
   149
e83f89d3b1f7 templates: add built-in files() function
Hannes Oldenburg <hannes.christian.oldenburg@gmail.com>
parents: 29717
diff changeset
   150
   $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
e83f89d3b1f7 templates: add built-in files() function
Hannes Oldenburg <hannes.christian.oldenburg@gmail.com>
parents: 29717
diff changeset
   151
29085
df838803c1d4 templater: add separate() template function
Martin von Zweigbergk <martinvonz@google.com>
parents: 28957
diff changeset
   152
- Separate non-empty arguments by a " "::
df838803c1d4 templater: add separate() template function
Martin von Zweigbergk <martinvonz@google.com>
parents: 28957
diff changeset
   153
df838803c1d4 templater: add separate() template function
Martin von Zweigbergk <martinvonz@google.com>
parents: 28957
diff changeset
   154
   $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
df838803c1d4 templater: add separate() template function
Martin von Zweigbergk <martinvonz@google.com>
parents: 28957
diff changeset
   155
21820
cce404b0c918 templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents: 20531
diff changeset
   156
- Modify each line of a commit description::
cce404b0c918 templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents: 20531
diff changeset
   157
cce404b0c918 templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents: 20531
diff changeset
   158
   $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
cce404b0c918 templatefilter: add splitlines function
Ryan McElroy <rmcelroy@fb.com>
parents: 20531
diff changeset
   159
18465
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   160
- Format date::
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   161
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   162
   $ 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
   163
26128
51f6940d3b4f templater: add optional timezone argument to localdate()
Yuya Nishihara <yuya@tcha.org>
parents: 25786
diff changeset
   164
- Display date in UTC::
51f6940d3b4f templater: add optional timezone argument to localdate()
Yuya Nishihara <yuya@tcha.org>
parents: 25786
diff changeset
   165
51f6940d3b4f templater: add optional timezone argument to localdate()
Yuya Nishihara <yuya@tcha.org>
parents: 25786
diff changeset
   166
   $ 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
   167
18465
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   168
- 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
   169
25004
e264d4c9629b help: rewrite template examples to use integer literals where appropriate
Yuya Nishihara <yuya@tcha.org>
parents: 24587
diff changeset
   170
   $ 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
   171
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   172
- 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
   173
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   174
   $ 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
   175
   'on branch {branch}')}\n"
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   176
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   177
- 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
   178
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   179
   $ 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
   180
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   181
- 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
   182
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   183
   $ 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
   184
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   185
- 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
   186
3aa8b4b36b64 help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents: 13591
diff changeset
   187
   $ 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
   188
f4b3bdc3019e help: adding example 'extras' printing to 'hg help templates'
Matthew Turk <matthewturk@gmail.com>
parents: 19390
diff changeset
   189
- 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
   190
20170
574f3b6e0e8b help: fix formatting of template example
Steve Hoelzer <shoelzer@gmail.com>
parents: 20016
diff changeset
   191
   $ 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
   192
25348
f26efa4f0eff templatekw: introduce active subkeyword from bookmarks keyword
Ryan McElroy <rmcelroy@fb.com>
parents: 25004
diff changeset
   193
- 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
   194
25786
35fa7c77c754 help: rewrite template examples to not use shell escaping
Yuya Nishihara <yuya@tcha.org>
parents: 25596
diff changeset
   195
   $ 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
   196
26485
43bf9471fae9 templater: introduce {latesttag()} function to match a pattern (issue4184)
Matt Harbison <matt_harbison@yahoo.com>
parents: 26234
diff changeset
   197
- 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
   198
43bf9471fae9 templater: introduce {latesttag()} function to match a pattern (issue4184)
Matt Harbison <matt_harbison@yahoo.com>
parents: 26234
diff changeset
   199
   $ 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
   200
20531
01a75c9d5b5e help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents: 20170
diff changeset
   201
- 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
   202
01a75c9d5b5e help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents: 20170
diff changeset
   203
   $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
21821
4a445dc5abff templater: introduce startswith function
Ryan McElroy <rmcelroy@fb.com>
parents: 21820
diff changeset
   204
26234
e4609ec959f8 templater: switch ctx of list expression to rev of revset() (BC)
Yuya Nishihara <yuya@tcha.org>
parents: 26128
diff changeset
   205
- 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
   206
e4609ec959f8 templater: switch ctx of list expression to rev of revset() (BC)
Yuya Nishihara <yuya@tcha.org>
parents: 26128
diff changeset
   207
   $ 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
   208
21821
4a445dc5abff templater: introduce startswith function
Ryan McElroy <rmcelroy@fb.com>
parents: 21820
diff changeset
   209
- Show only commit descriptions that start with "template"::
4a445dc5abff templater: introduce startswith function
Ryan McElroy <rmcelroy@fb.com>
parents: 21820
diff changeset
   210
25786
35fa7c77c754 help: rewrite template examples to not use shell escaping
Yuya Nishihara <yuya@tcha.org>
parents: 25596
diff changeset
   211
   $ hg log --template "{startswith('template', firstline(desc))}\n"
21846
8f23f8096606 templater: introduce word function
Ryan McElroy <rmcelroy@fb.com>
parents: 21821
diff changeset
   212
8f23f8096606 templater: introduce word function
Ryan McElroy <rmcelroy@fb.com>
parents: 21821
diff changeset
   213
- 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
   214
25004
e264d4c9629b help: rewrite template examples to use integer literals where appropriate
Yuya Nishihara <yuya@tcha.org>
parents: 24587
diff changeset
   215
   $ hg log --template "{word(0, desc)}\n"