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

Template locations

Templates are loaded from directories in the following order:

  • If it exists, ${XDG_DATA_HOME:~/.local}/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


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.


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).


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


The following variables are available for use in templates

View group


The width of the current terminal window

list.txt data


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


Set to the maximum length of the bug IDs to display


The bug states being searched/listed


The display order


The search term being listed, if any

issue.txt data


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


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


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


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

Edit group


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


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

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.


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


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.


This filter applies a colour to text, if possible. This functionality requires termcolor, if the module is unavailable the filter is simply a no-op.

When directing output to a pipe or using a terminal that is incapable of displaying colours the text is passed through unchanged.

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

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


This filter is also available under the synonym colorize.


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.


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


The purpose of this filter is to pretty print Markdown formatted text, which is the format used by GitHub issues. It only handles headings, horizontal rules and emphasis currently.

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

{{ comment.body | wordwrap(break_long_words=False) | term_markdown }}


We pass the text through Jinja’s built-in wordwrap() filter prior to formatting with term_markdown so that the terminal escape sequences aren’t included in the line width calculations for wrapping.

Table Of Contents

Previous topic


Next topic


This Page