annotate mercurial/help/templates.txt @ 13585:2e80d495592a

templates: generate keyword help dynamically

Mercurial allows you to customize output of commands through
templates. You can either pass in a template from the command
line, via the --template option, or select an existing
template-style (--style).

You can customize output for any "log-like" command: log,
outgoing, incoming, tip, parents, heads and glog.

Four styles are packaged with Mercurial: default (the style used
when no explicit preference is passed), compact, changelog,
and xml.
Usage::

    $ hg log -r1 --style changelog

A template is a piece of text, with markup to invoke variable
expansion::

    $ hg log -r1 --template "{node}\n"
    b56ce7b07c52de7d5fd79fb89701ea538af65746

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

List of filters:

:addbreaks: Any text. Add an XHTML "<br />" tag before the end of
    every line except the last.

:age: Date. Returns a human-readable date/time difference between the
    given date/time and the current date/time.

:basename: Any text. Treats the text as a path, and returns the last
    component of the path after splitting by the path separator
    (ignoring trailing separators). For example, "foo/bar/baz" becomes
    "baz" and "foo/bar//" becomes "bar".

:stripdir: Treat the text as path and strip a directory level, if
    possible. For example, "foo" and "foo/bar" becomes "foo".

:date: Date. Returns a date in a Unix date format, including the
    timezone: "Mon Sep 04 15:13:13 2006 0700".

:domain: Any text. Finds the first string that looks like an email
    address, and extracts just the domain component. Example: ``User
    <[e-mail]>`` becomes ``example.com``.

:email: Any text. Extracts the first string that looks like an email
    address. Example: ``User <[e-mail]>`` becomes
    ``[e-mail]``.

:escape: Any text. Replaces the special XML/XHTML characters "&", "<"
    and ">" with XML entities.

:hex: Any text. Convert a binary Mercurial node identifier into
    its long hexadecimal representation.

:fill68: Any text. Wraps the text to fit in 68 columns.

:fill76: Any text. Wraps the text to fit in 76 columns.

:firstline: Any text. Returns the first line of text.

:nonempty: Any text. Returns '(none)' if the string is empty.

:hgdate: Date. Returns the date as a pair of numbers: "1157407993
    25200" (Unix timestamp, timezone offset).

:isodate: Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
    +0200".

:isodatesec: Date. Returns the date in ISO 8601 format, including
    seconds: "2009-08-18 13:00:13 +0200". See also the rfc3339date
    filter.

:localdate: Date. Converts a date to local date.

:obfuscate: Any text. Returns the input text rendered as a sequence of
    XML entities.

:person: Any text. Returns the text before an email address.

:rfc822date: Date. Returns a date using the same format used in email
    headers: "Tue, 18 Aug 2009 13:00:13 +0200".

:rfc3339date: Date. Returns a date using the Internet date format
    specified in RFC 3339: "2009-08-18T13:00:13+02:00".

:short: Changeset hash. Returns the short form of a changeset hash,
    i.e. a 12 hexadecimal digit string.

:shortdate: Date. Returns a date like "2006-09-18".

:stringify: Any type. Turns the value into text by converting values into
    text and concatenating them.

:strip: Any text. Strips all leading and trailing whitespace.

:tabindent: Any text. Returns the text, with every line except the
     first starting with a tab character.

:urlescape: Any text. Escapes all "special" characters. For example,
    "foo bar" becomes "foo%20bar".

:user: Any text. Returns the user portion of an email address.