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 byXDG_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 buglist.txt
for formatting list output
edit
group templates currently include:
default.mkd
for general use, such as in commenting on a bugopen.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 thehubugs show -p
option
-
patch_only
(bool)¶ True, if the user provided the
hubugs show -o
option
Edit group¶
-
comment_char
(str)¶ The character to use for comments in templates, defaults to
#
. Seecore.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.
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.