help/templates.txt

help: move help topics from mercurial/help.py to help/*.txt

The help topics are loaded on demand so we wont hit the disk unless we
really have to.

    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.