cryzed / git_revision

A plugin that integrates Git with Pelican.

git_revision

A plugin that integrates Git with Pelican.

If not available in the content's metadata, git_revision will set the added and modified date for each page and article that is version controlled by Git. All previous revisions of the content will be written and accessible by using the git object attached to each content object. The full information contained in the commit and the file path relative to the Git repository are also accessible.

See the usage section for more details and a working example.

Requirements

git_revision requires GitPython.

pip install GitPython

Details

The URLs generated by the plugin will look like this: {SITEURL}/<name>/<hexsha>/, where name is the last component of the original content's URL and hexsha the commit checksum provided by Git in hex format. To clarify:

• {SITEURL}/article/ -> {SITEURL}/article/<hexsha>/
• {SITEURL}/article.html -> {SITEURL}/article/<hexsha>/

Currently this behavior is hardcoded but easily adjustable by modifying the source code.

Usage

The git object has the following attributes:

• commit: a GitPython Objects.Commit object
• file_path: The file path relative to the repository path
• revisions: A list of all other revisions for this content
• previous_revision: None or a reference to the previous revision for this content
• next_revision: None or a reference to the next revision for this content

Each revision is a content object, i.e. an article or page. To access for example the commit information of a previous revision, you could do this: article.git.previous_revision.git.commit.

Here's an example on how to use it in a template:

{% if article.git %}
{% set commit = article.git.commit %}
<div class="container row-fluid">
    {% set previous_revision = article.git.previous_revision %}
    {% if previous_revision %}
    <a href="{{ SITEURL }}/{{ previous_revision.url }}">«</a>
    {% else %}
    «
    {% endif %}

    <a class="btn btn-link" data-toggle="collapse" data-target="#revision">{{ commit.hexsha|truncate(7, end='') }}</a>

    {% set next_revision = article.git.next_revision %}
    {% if next_revision %}
    <a href="{{ SITEURL }}/{{ next_revision.url }}">»</a>
    {% else %}
    »
    {% endif %}
    <div id="revision" class="collapse">
        <p>{{ commit.summary|e }}</p>
        {% set statistics = commit.stats.files[article.git.file_path] %}
        {{ statistics.lines }} lines changed:
        <ul>
            <li><span style="color: green">{{ statistics.insertions }} insertions(+)</span></li>
            <li><span style="color: red">{{ statistics.deletions }} deletions(-)</span></li>
        </ul>
    </div>
</div>
{% endif %}

Credits

Thanks to Avaris and winlu in the #pelican channel for helpful suggestions and helping me figuring out Pelican's internals quickly.