{"id":6887,"library":"sphinx-last-updated-by-git","title":"Sphinx Last Updated by Git","description":"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.","status":"active","version":"0.3.8","language":"en","source_language":"en","source_url":"https://github.com/mgeier/sphinx-last-updated-by-git/","tags":["sphinx","documentation","git","build-tool","extension","timestamp"],"install":[{"cmd":"pip install sphinx-last-updated-by-git","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This is a Sphinx extension and requires Sphinx to build documentation. Python 3.7+ is also required.","package":"Sphinx","optional":false},{"reason":"Relies on Git commands to retrieve commit history for last updated timestamps. If Git is not installed or available, warnings will be issued, and timestamps may be `None`.","package":"Git","optional":false}],"imports":[{"note":"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.","symbol":"'sphinx_last_updated_by_git'","correct":"# in conf.py\nextensions = [\n    'sphinx_last_updated_by_git',\n]"}],"quickstart":{"code":"# conf.py\nimport os\nimport sys\n\n# Minimal Sphinx configuration\nproject = 'My Git Docs'\ncopyright = '2026, My Org'\nauthor = 'My Org'\nrelease = '0.1'\n\nextensions = [\n    'sphinx_last_updated_by_git',\n]\n\n# Optional: Customize the format of the last updated date\n# html_last_updated_fmt = '%Y-%m-%d %H:%M:%S %Z'\n\n# Optional: Exclude specific files/commits from last updated calculation\n# git_exclude_patterns = ['**/auto_generated/*.rst']\n# git_exclude_commits = ['a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0']\n\nhtml_theme = 'alabaster' # Ensure your theme supports displaying 'last_updated'\n\n# Create a simple index.rst and page1.rst in your docs directory:\n# index.rst:\n# Welcome to My Git Docs!\n# ======================\n#\n# This is the main index page.\n#\n# .. toctree::\n#    :maxdepth: 2\n#    :caption: Contents:\n#\n#    page1\n#\n# page1.rst:\n# My First Page\n# =============\n#\n# This content was last updated by Git.","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<0.3.0 (for P3.5 users), 0.3.0+ (requires P3.7+)"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade Sphinx to version 5.2 or newer if you encounter incorrect 'last updated' dates.","message":"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.","severity":"gotcha","affected_versions":"Sphinx 5.0, 5.1"},{"fix":"When using Sphinx 7.2 or a later version, ensure you upgrade `sphinx-last-updated-by-git` to 0.3.6 or newer.","message":"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.","severity":"gotcha","affected_versions":"`sphinx-last-updated-by-git < 0.3.6` with Sphinx 7.2+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}