annotate help/templates.txt @ 9704:90e968899c72

help: markup email addresses as inline literals

Otherwise we get useless links to [e-mail] in the HTML version
of the man pages.

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.

Three styles are packaged with Mercurial: default (the style used
when no explicit preference is passed), compact and changelog.
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:

:author:    String. The unmodified author of the changeset.
:branches:  String. The name of the branch on which the changeset
            was committed. Will be empty if the branch name was
            default.
:date:      Date information. The date when the changeset was
            committed.
:desc:      String. The text of the changeset description.
:diffstat:  String. Statistics of changes with the following
            format: "modified files: +added/-removed lines"
:files:     List of strings. All files modified, added, or removed
            by this changeset.
:file_adds: List of strings. Files added by this changeset.
:file_mods: List of strings. Files modified by this changeset.
:file_dels: List of strings. Files removed by this changeset.
:node:      String. The changeset identification hash, as a
            40-character hexadecimal string.
:parents:   List of strings. The parents of the changeset.
:rev:       Integer. The repository-local changeset revision
            number.
:tags:      List of strings. Any tags associated with the
            changeset.
:latesttag: String. Most recent global tag in the ancestors of this
            changeset.
:latesttagdistance: Integer. Longest path to the latest tag.

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. 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.
: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-byte hexadecimal string.
:shortdate:   Date. Returns a date like "2006-09-18".
: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.