Using Git Information
Introduction
A frequent requirement for the documentation of software projects, is to insert version information. Nowadays, the tool of choice for version control is git.
Several specific plugins exist, this comes out of the box with mkdocs-macros. Plus, covers a wide range of use cases, from the simplest to more complicated ones.
How to access
Providing of course the site is under a git repository,
information is provided out of the box in a page, through the git
variable.
To have the full string (corresponding to git log -1
on the command line):
{{ git.raw }}
To have, e.g. the short hash of the last commit, the date and the author:
{{ git.short_commit}} ({{ git.date}}) by {{ git.author}}
For the date, you may use the standard Python methods, e.g.
strftime()
:
{{ git.date.strftime("%b %d, %Y %H:%M:%S") }}
Testing for the presence of git repo
If the plugin cannot find the git executable,
or if the page is not in a
git repository, then git.status
is set to False.
If you want to print git information only if applicable:
{% if git.status %}
Git: {{ git.short_commit }}
{% endif %}
If the page is indeed in a git repo, but git.status
is still False, try displaying {{ git.error }}
Catalogue
Here is a list of attributes of the git object:
Attribute | Description |
---|---|
short_commit |
short hash of the last commit (e.g. 2bd7950) |
commit |
long hash of the last commit |
author |
author's name |
author_email |
author's email |
committer |
committer's name |
committer_email |
committer's email |
tag |
last active tag of the repo |
short_tag |
last active tag of the repo, abbreviated |
date |
full date of the commit (as a date object) |
date_ISO |
full date of the commit (as an ISO string) |
message |
full message of the last commit |
raw |
string description of the last commit |
root_dir |
root dir of the git repository |
status |
is git present? |
Note
Most of the time, you might be interested in the author's information. For more information on the difference between author and committer, see the Pro Git Book, chapter 2.3
Tip
To get the full list all attributes of the git object:
{{ context(git)| pretty }}
Date of the last commit
In order to obtain a printout of the date of the last commit, you can use:
{{ git.date }}
which would return e.g.:
2020-05-13 16:08:52+02:00
Note
For the commit dates (date
and date_ISO
) the common sense choice has been to use
git's committer date, since that guarantees that if the commit has been
modified (rebased, etc.), the date has been updated.
Since it is a datetime
object, you can also use any of the usual attributes
(.year
, .month
), as well as the
strftime()
formatting
method, e.g.:
{{ git.date.strftime("%b %d, %Y %H:%M:%S") }}
which would return e.g.
May 13, 2020 16:08:52
tag
and short_tag
The tag attribute shows the full description of the tag, for
example v1.0.4-14-g2414721
. Meanwhile, short_tag
shows the
tag name without any suffix, for example v1.0.4
. The later can
be useful when showing the latest release.
Tip: Is this really a git repo?
In case you are not sure that there really is a git repo, you could use:
{{ git.date or now() }}
Which would give you at least the build date for the static website.
Note that now()
is also a datetime object.