--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/helptext/templates.txt Wed Nov 13 21:52:25 2019 -0500
@@ -0,0 +1,215 @@
+Mercurial allows you to customize output of commands through
+templates. You can either pass in a template or select an existing
+template-style from the command line, via the --template option.
+
+You can customize output for any "log-like" command: log,
+outgoing, incoming, tip, parents, and heads.
+
+Some built-in styles are packaged with Mercurial. These can be listed
+with :hg:`log --template list`. Example usage::
+
+ $ hg log -r1.0::1.1 --template changelog
+
+A template is a piece of text, with markup to invoke variable
+expansion::
+
+ $ hg log -r1 --template "{node}\n"
+ b56ce7b07c52de7d5fd79fb89701ea538af65746
+
+Keywords
+========
+
+Strings in curly braces are called keywords. The availability of
+keywords depends on the exact context of the templater. These
+keywords are usually available for templating a log-like command:
+
+.. keywordsmarker
+
+The "date" keyword does not produce human-readable output. If you
+want to use a date in your output, you can use a filter to process
+it. Filters are functions which return a string based on the input
+variable. Be sure to use the stringify filter first when you're
+applying a string-input filter to a list-like input variable.
+You can also use a chain of filters to get the desired output::
+
+ $ hg tip --template "{date|isodate}\n"
+ 2008-08-21 18:22 +0000
+
+Filters
+=======
+
+List of filters:
+
+.. filtersmarker
+
+Note that a filter is nothing more than a function call, i.e.
+``expr|filter`` is equivalent to ``filter(expr)``.
+
+Functions
+=========
+
+In addition to filters, there are some basic built-in functions:
+
+.. functionsmarker
+
+Operators
+=========
+
+We provide a limited set of infix arithmetic operations on integers::
+
+ + for addition
+ - for subtraction
+ * for multiplication
+ / for floor division (division rounded to integer nearest -infinity)
+
+Division fulfills the law x = x / y + mod(x, y).
+
+Also, for any expression that returns a list, there is a list operator::
+
+ expr % "{template}"
+
+As seen in the above example, ``{template}`` is interpreted as a template.
+To prevent it from being interpreted, you can use an escape character ``\{``
+or a raw string prefix, ``r'...'``.
+
+The dot operator can be used as a shorthand for accessing a sub item:
+
+- ``expr.member`` is roughly equivalent to ``expr % '{member}'`` if ``expr``
+ returns a non-list/dict. The returned value is not stringified.
+- ``dict.key`` is identical to ``get(dict, 'key')``.
+
+Aliases
+=======
+
+New keywords and functions can be defined in the ``templatealias`` section of
+a Mercurial configuration file::
+
+ <alias> = <definition>
+
+Arguments of the form `a1`, `a2`, etc. are substituted from the alias into
+the definition.
+
+For example,
+
+::
+
+ [templatealias]
+ r = rev
+ rn = "{r}:{node|short}"
+ leftpad(s, w) = pad(s, w, ' ', True)
+
+defines two symbol aliases, ``r`` and ``rn``, and a function alias
+``leftpad()``.
+
+It's also possible to specify complete template strings, using the
+``templates`` section. The syntax used is the general template string syntax.
+
+For example,
+
+::
+
+ [templates]
+ nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
+
+defines a template, ``nodedate``, which can be called like::
+
+ $ hg log -r . -Tnodedate
+
+A template defined in ``templates`` section can also be referenced from
+another template::
+
+ $ hg log -r . -T "{rev} {nodedate}"
+
+but be aware that the keywords cannot be overridden by templates. For example,
+a template defined as ``templates.rev`` cannot be referenced as ``{rev}``.
+
+A template defined in ``templates`` section may have sub templates which
+are inserted before/after/between items::
+
+ [templates]
+ myjson = ' {dict(rev, node|short)|json}'
+ myjson:docheader = '\{\n'
+ myjson:docfooter = '\n}\n'
+ myjson:separator = ',\n'
+
+Examples
+========
+
+Some sample command line templates:
+
+- Format lists, e.g. files::
+
+ $ hg log -r 0 --template "files:\n{files % ' {file}\n'}"
+
+- Join the list of files with a ", "::
+
+ $ hg log -r 0 --template "files: {join(files, ', ')}\n"
+
+- Join the list of files ending with ".py" with a ", "::
+
+ $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
+
+- Separate non-empty arguments by a " "::
+
+ $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
+
+- Modify each line of a commit description::
+
+ $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
+
+- Format date::
+
+ $ hg log -r 0 --template "{date(date, '%Y')}\n"
+
+- Display date in UTC::
+
+ $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
+
+- Output the description set to a fill-width of 30::
+
+ $ hg log -r 0 --template "{fill(desc, 30)}"
+
+- Use a conditional to test for the default branch::
+
+ $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
+ 'on branch {branch}')}\n"
+
+- Append a newline if not empty::
+
+ $ hg tip --template "{if(author, '{author}\n')}"
+
+- Label the output for use with the color extension::
+
+ $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
+
+- Invert the firstline filter, i.e. everything but the first line::
+
+ $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
+
+- Display the contents of the 'extra' field, one per line::
+
+ $ hg log -r 0 --template "{join(extras, '\n')}\n"
+
+- Mark the active bookmark with '*'::
+
+ $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
+
+- Find the previous release candidate tag, the distance and changes since the tag::
+
+ $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
+
+- Mark the working copy parent with '@'::
+
+ $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
+
+- Show details of parent revisions::
+
+ $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
+
+- Show only commit descriptions that start with "template"::
+
+ $ hg log --template "{startswith('template', firstline(desc))}\n"
+
+- Print the first word of each line of a commit message::
+
+ $ hg log --template "{word(0, desc)}\n"