keywords - Keyword templating (e.g. Date, Authors, etc.)

Version Not specified
Branch lp:bzr-keywords
Home page https://launchpad.net/bzr-keywords
Owner ian-clatworthy
GNU/Linux Yes
Windows Yes
Mac OS X Yes

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
Committer the committer (name and email) of the last change
Authors the authors (names and emails) of the last change
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)

If you want finer control over the formatting of names and email addresses, you can use the following keywords.

Note: If you have more than 3 authors for a given revision, please ask on the Bazaar mailing list for an enhancement to support the number you need.

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.

cat

Purpose

Write the contents of a file as of a given revision to standard output.

Usage

bzr cat FILENAME

Options

-v, --verbose Display more information.
--name-from-revision
 The path name in the old tree.
--keywords=ARG Keyword expansion style.
-q, --quiet Only display errors and warnings.
-d ARG, --directory=ARG
 Branch to operate on, instead of working directory
--filters Apply content filters to display the convenience form.
--usage Show usage message and options.
-r ARG, --revision=ARG
 See “help revisionspec” for details.
-h, --help Show help message.

Description

If no revision is nominated, the last revision is used.

Note: Take care to redirect standard output when using this command on a binary file.

The --keywords option specifies the keywords expansion style. By default (raw style), no expansion is done. Other styles enable expansion in a cooked mode where both the keyword and its value are displayed inside $ markers, or in numerous publishing styles - publish, publish-values and publish-names - where the $ markers are completely removed. The publishing styles do not support round-tripping back to the raw content but are useful for improving the readability of published web pages for example.

Note: Files must have the keywords preference defined for them in order for the --keywords option to take effect. In particular, the preference specifies how keyword values are encoded for different filename patterns. See bzr help keywords for more information on how to specify the required preference using rules.

See also

ls

export

Purpose

Export current or past revision to a destination directory or archive.

Usage

bzr export DEST [BRANCH_OR_SUBDIR]

Options

-v, --verbose Display more information.
--format=ARG Type of file to export to.
--keywords=ARG Keyword expansion style.
-q, --quiet Only display errors and warnings.
--per-file-timestamps
 Set modification time of files to that of the last revision in which it was changed.
-d ARG, --directory=ARG
 Branch to operate on, instead of working directory
--filters Apply content filters to export the convenient form.
--usage Show usage message and options.
-r ARG, --revision=ARG
 See “help revisionspec” for details.
--root=ARG Name of the root directory inside the exported file.
-h, --help Show help message.

Description

If no revision is specified this exports the last committed revision.

Format may be an “exporter” name, such as tar, tgz, tbz2. If none is given, try to find the format with the extension. If no extension is found exports to a directory (equivalent to –format=dir).

If root is supplied, it will be used as the root directory inside container formats (tar, zip, etc). If it is not supplied it will default to the exported filename. The root option has no effect for ‘dir’ format.

If branch is omitted then the branch containing the current working directory will be used.

Note: Export of tree with non-ASCII filenames to zip is not supported.

Supported formats Autodetected by extension
dir (none)
tar .tar
tbz2 .tar.bz2, .tbz2
tgz .tar.gz, .tgz
zip .zip

The --keywords option specifies the keywords expansion style. By default (raw style), no expansion is done. Other styles enable expansion in a cooked mode where both the keyword and its value are displayed inside $ markers, or in numerous publishing styles - publish, publish-values and publish-names - where the $ markers are completely removed. The publishing styles do not support round-tripping back to the raw content but are useful for improving the readability of published web pages for example.

Note: Files must have the keywords preference defined for them in order for the --keywords option to take effect. In particular, the preference specifies how keyword values are encoded for different filename patterns. See bzr help keywords for more information on how to specify the required preference using rules.