Keyword Templating
==================

Keyword templating is provided as a content filter where Bazaar internally
stores a canonical format but outputs a convenience format. See
``bzr help content-filters`` for general information about using these.

Note: Content filtering is only supported in recently added formats,
e.g. 1.14.

Keyword templates are specified using the following patterns:

 * in canonical/compressed format: $Keyword$
 * in convenience/expanded format: $Keyword: value $

When expanding, the existing text is retained if an unknown keyword is
found. If the keyword is already expanded but known, the value is replaced.
When compressing, values are always removed, whether the keyword is known
or not.

Keyword filtering needs to be enabled for selected branches and files via
rules. See ``bzr help rules`` for general information on defining rules.
For example, to enable keywords for all ``txt`` files on your system, add
these lines to your ``BZR_HOME/rules`` file::

  [name *.txt]
  keywords = on

To disable keywords for ``txt`` files but enable them for ``html`` files::

  [name *.txt]
  keywords = off

  [name *.html]
  keywords = xml_escape

``xml_escape`` enables keyword expansion but it escapes special characters
in keyword values so they can be safely included in HTML or XML files.

The currently supported keywords are given below.

 =============  =========================================================
 Keyword        Description
 =============  =========================================================
 Date           the date and time the file was last modified
 Author         the author (name and email) of the last change
 Author-Email   just the email address of the author
 Revision-Id    the unique id of the revision that last changed the file
 Path           the relative path of the file in the tree
 Filename       just the name part of the relative path
 Directory      just the directory part of the relative path
 File-Id        the unique id assigned to this file
 Now            the current date and time
 User           the current user (name and email)
 User-Email     just the email address of the current user
 =============  =========================================================

By default, dates/times are output using this format::

  YYYY-MM-DD HH:MM:SS+HH:MM

To specify a custom format, add a configuration setting to
``BZR_HOME/bazaar.conf`` like this::

  keywords.format.Now = %A, %B %d, %Y

The last part of the key needs to match the keyword name. The value must be
a legal strftime (http://docs.python.org/lib/module-time.html) format.