Sphinx Last Updated by Git

0.3.8 · active · verified Wed Apr 15

sphinx-last-updated-by-git is a Sphinx extension that automatically retrieves and displays the 'last updated' timestamp for each documentation page directly from your Git repository. It considers the author date of the last relevant Git commit, including checks for included files and other dependencies to ensure the most recent timestamp. The current version is 0.3.8, and the project maintains a regular release cadence with updates addressing Sphinx compatibility and new features.

Warnings

breaking Version 0.3.0 dropped support for Python 3.5. Users on older Python versions must upgrade to at least Python 3.7 or stick to `sphinx-last-updated-by-git < 0.3.0`. The current requirement is Python >= 3.7.
Fix: Upgrade your Python environment to 3.7 or newer, or pin `sphinx-last-updated-by-git` to a version older than 0.3.0.
gotcha The extension relies on Git being installed and the project being a Git repository. When using Git shallow clones (`--depth`), the 'last updated' commit for long-unchanged files might not be available, resulting in `None` timestamps and build warnings. Warnings are also issued if Git is not found or subprocess errors occur.
Fix: Ensure Git is installed and available in the PATH. For shallow clones, consider a deeper clone. Warnings (e.g., `git.command_not_found`, `git.subprocess_error`) can be suppressed in `conf.py` using `suppress_warnings`.
gotcha Sphinx versions 5.0 and 5.1 contained a regression in how dependencies are determined, which could lead to incorrect 'last changed' dates due to spurious dependencies. This issue was resolved in Sphinx 5.2 and above.
Fix: Upgrade Sphinx to version 5.2 or newer if you encounter incorrect 'last updated' dates.
gotcha Version 0.3.6 added specific support for a changed behavior of the `source-read` event in Sphinx 7.2. Using older versions of `sphinx-last-updated-by-git` with Sphinx 7.2 or newer may lead to unexpected behavior.
Fix: When using Sphinx 7.2 or a later version, ensure you upgrade `sphinx-last-updated-by-git` to 0.3.6 or newer.
gotcha The 'last updated' timestamp is added to the Sphinx HTML context, but your chosen Sphinx theme (or a custom theme template) must explicitly display this information. Without theme support, the date will not be visible on generated pages.
Fix: Verify that your Sphinx theme's templates (`layout.html`, `footer.html`, etc.) include `{{ last_updated }}` or a similar mechanism to display the date. The extension sets `html_last_updated_fmt` to an empty string by default, making the variable available for themes to format.

Install

pip install sphinx-last-updated-by-git Install with pip

Imports

'sphinx_last_updated_by_git'
```
# in conf.py
extensions = [
    'sphinx_last_updated_by_git',
]
```
The extension is enabled by adding its name to the `extensions` list in your Sphinx `conf.py` file. No direct Python import statement is typically used in documentation source files.

Quickstart

To quickly enable `sphinx-last-updated-by-git`, install the package and add `'sphinx_last_updated_by_git'` to the `extensions` list in your `conf.py`. Ensure your chosen Sphinx theme is configured to display the `last_updated` variable in its templates. The extension sets `html_last_updated_fmt` to an empty string by default, making the timestamp available for display.

# conf.py
import os
import sys

# Minimal Sphinx configuration
project = 'My Git Docs'
copyright = '2026, My Org'
author = 'My Org'
release = '0.1'

extensions = [
    'sphinx_last_updated_by_git',
]

# Optional: Customize the format of the last updated date
# html_last_updated_fmt = '%Y-%m-%d %H:%M:%S %Z'

# Optional: Exclude specific files/commits from last updated calculation
# git_exclude_patterns = ['**/auto_generated/*.rst']
# git_exclude_commits = ['a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0']

html_theme = 'alabaster' # Ensure your theme supports displaying 'last_updated'

# Create a simple index.rst and page1.rst in your docs directory:
# index.rst:
# Welcome to My Git Docs!
# ======================
#
# This is the main index page.
#
# .. toctree::
#    :maxdepth: 2
#    :caption: Contents:
#
#    page1
#
# page1.rst:
# My First Page
# =============
#
# This content was last updated by Git.

view raw JSON →