Skip to main content

Get the "last updated" time for each Sphinx page from Git

Project description

This is a little Sphinx extension that does exactly that. It also checks for included files and other dependencies and uses their “last updated” time if it’s more recent. For each file, the “author date” of the Git commit where it was last changed is taken to be its “last updated” time. Uncommitted changes are ignored.

If a page doesn’t have a source file, its last_updated time is set to None.

The default value for html_last_updated_fmt is changed from None to the empty string.

  1. Install the Python package sphinx-last-updated-by-git

  2. Add 'sphinx_last_updated_by_git' to extensions in your

  3. Run Sphinx!

  • If a source file is not tracked by Git (e.g. because it has been auto-generated on demand by autosummary_generate) but its dependencies are, the last_updated time is taken from them. If you don’t want this to happen, use git_untracked_check_dependencies = False.

  • If a source file is not tracked by Git, its HTML page doesn’t get a source link. If you do want those pages to have a sourcelink, set git_untracked_show_sourcelink = True. Of course, in this case html_copy_source and html_show_sourcelink must also be True, and the theme you are using must support source links in the first place.

  • By default, timestamps are displayed using the local time zone. You can specify a datetime.timezone object (or any tzinfo subclass instance) with the configuration option git_last_updated_timezone. You can also use any string recognized by babel, e.g. git_last_updated_timezone = 'Pacific/Auckland'.

  • By default, the “last updated” timestamp is added as an HTML <meta> tag. This can be disabled by setting the configuration option git_last_updated_metatags to False.

  • Files can be excluded from the last updated date calculation by passing a list of exclusion patterns to the configuration option git_exclude_patterns. These patterns are checked on both source files and dependencies and are treated the same way as Sphinx’s exclude_patterns.

  • Individual commits can be excluded from the last updated date calculation by passing a list of commit hashes to the configuration option git_exclude_commits.

  • When using a “Git shallow clone” (with the --depth option), the “last updated” commit for a long-unchanged file might not have been checked out. In this case, the last_updated time is set to None (and a warning is shown during the build).

    This might happen on because they use shallow clones by default. To avoid this problem, you can edit your config file .readthedocs.yml:

    version: 2
      os: "ubuntu-22.04"
        python: "3"
          - git fetch --unshallow || true

    For more details, read the docs.

    This might also happen when using Github Actions, because actions/checkout also uses shallow clones by default. This can be changed by using fetch-depth: 0:

      - uses: actions/checkout@v3
          fetch-depth: 0

    If you only want to get rid of the warning (without actually fixing the problem), use this in your

    suppress_warnings = ['git.too_shallow']
  • When a project on using their default theme sphinx_rtd_theme was created before October 20th 2020, the date will not be displayed in the footer.

    One work-around is to enable the (undocumented) feature flag USE_SPHINX_LATEST.

    Another work-around is to override the defaults by means of a requirements.txt file containing something like this:


    See also issue #1.

  • In Sphinx versions 5.0 and 5.1, there has been a regression in how dependencies are determined. This could lead to spurious dependencies which means that some “last changed” dates were wrong. This has been fixed in Sphinx version 5.2 and above.

    See also issue #40.


BSD-2-Clause (same as Sphinx itself), for more information take a look at the LICENSE file.

Similar stuff

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_last_updated_by_git-0.3.7.tar.gz (10.7 kB view hashes)

Uploaded Source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page