Templates

Output is produced from templates using Jinja. Before writing your own templates you should read the awesome Jinja template designer documentation.

Note

If you create some cool templates of your own please consider posting them in an issue or pushing them to a fork on GitHub, so that others can benefit.

Template locations

Templates are loaded from directories in the following order:

  • If it exists, ${XDG_DATA_HOME:~/.local/share}/hubugs/templates

  • Any hubugs/templates directory in the directories specified by XDG_DATA_DIRS

  • The package’s templates directory

For information on the usage of XDG_DATA_HOME and XDG_DATA_DIRS read XDG Base Directory Specification.

Note

For OS X users there is a fallback to ~/Library/Application Support, if XDG_DATA_HOME is unset.

Precedence

The first name match in the order specified above selects the template, so a view/list.txt in $XDG_DATA_HOME/hubugs/templates overrides the view/list.txt provided in the hubugs package.

Template sets

You can specify the template set to use by defining a hubugs.templates setting in your git configuration files. For example:

▶ git config --global hubugs.templates my_templates

You can also set project specific template sets by editing a repository’s config. See git-config(1).

Naming

Templates are separated in to two groups. The first group, view, is for templates used in directly producing consumable output(such as from the list subcommand). The second group, edit, is for templates used to generate input files for editing text(such as in the open subcommand).

view group templates currently include:

  • issue.txt for formatting a single bug

  • list.txt for formatting list output

edit group templates currently include:

  • default.mkd for general use, such as in commenting on a bug

  • open.mkd for opening(or editing) bugs

Data

The following variables are available for use in templates

View group

columns(int)

The width of the current terminal window

list.txt data

project(Repository)

The current project’s repository data. See Repository objects.

bugs(list)

Contains the sorted list of bugs to display, if any. See Bug objects.

id_len(int)

Set to the maximum length of the bug IDs to display

state(str)

The bug states being searched/listed

order(str)

The display order

term(str)

The search term being listed, if any

issue.txt data

project(Repository)

The current project’s repository data. See Repository objects.

bug(list)

Contains the sorted list of bugs to display, if any. See Bug objects

comments(list)

When displaying a single bug this contains the list of comments associated with a bug, if any. See Comment objects

full(bool)

True, if the user provided the hubugs show -f option

patch(str)

The content found at the location in Bug.patch_url, if the user provided the hubugs show -p option

patch_only(bool)

True, if the user provided the hubugs show -o option

Edit group

title(str)

The current bug title in edit subcommand sessions. See Bug.title

body(str)

The current bug body in edit subcommand sessions, if any. See Bug.body

comment_char(str)

The character to use for comments in templates, defaults to #. See core.commentchar in git-config(1)

All groups

Jinja templates support object attribute and method access, so an individual bug object’s created_at attribute can be called with a strftime() method for custom date output. For example, {{ bug.created_at.strftime("%a, %e %b %Y %H:%M:%S %z") }} can be used to output an RFC 2822-style date stamp.

If you’re authoring your own templates and you find you need extra data for their generation open an issue.

Filters

hubugs defines the following filters beyond the huge range of excellent built-in filters in Jinja:

Note

If you write extra filters that you believe could be of use to other hubugs users please consider posting them in an issue or pushing them to a fork on GitHub, so that others can benefit from your work.

colourise

This filter applies a colour to text, if possible.

For example, to show a bug’s title attribute in red:

{{ bug.title | colourise('red') }}

or to display black text on a red background:

{{ bug.title | colourise('black on red') }}

Note

This filter is also available under the synonym colorize.

highlight

This filter highlights text using Pygments. You can specify the lexer to be used, and also the formatter.

For example, to highlight a chunk of text as Python:

{{ text | highlight('python') }}

To do the same using the 256-colour mode of Pygments:

{{ text | highlight('python', 'terminal256') }}

See the output of pygmentize -L for the list of available lexers and formatters.

html2text

This filter converts HTML to a plain text representation using html2text.

markdown

The purpose of this filter is to convert the Markdown formatted text from a GitHub issue to html. The excellent misaka package is used to provide the conversion.

In the default templates it is used to render bug bodies:

{{ comment.body | markdown | html2text }}

Note

We ping-pong the conversion from Markdown to HTML as it produces a prettier text representation of the comment. We benefit from uniform newline usage and clean word wrapping of the output.

relative_time

This filter is used to generate a human-readable relative timestamp from a datetime object.

For example, to display a bug’s created_at attribute as a relative time:

{{ bug.created_at | relative_time }}

which could produce output such as:

about two months ago