{{ git.date }} displays the author date instead of the commit date

[Kryptos-FR]

Description of issue

Despite what the documentation is saying, the date returned by {{ git.date }} is the author date, not the commit date.

This causes weird and incorrect date display after cherry-picking a commit that could be weeks or months old.

Suggested solution

Use the actual commit date or provide a way to get either: for instance {{ git.commit_date }} and {{ git.author_date }}.

A command-line that can display both is git log -1 --pretty=fuller.

Notes

Plugin version: 0.6.3

[github-actions[bot]]

Welcome to this project and thank you!' first issue

[fralau]

Thanks a lot. I am not a specialist of git, so this is well received.

Could you refer me to some git documentation where this question is covered?

[timvink]

@fralau If it helps, you can have a look at the internals of mkdocs-git-revision-date-localized-plugin and mkdocs-git-authors-plugin

Especially this section is interesting: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/blob/e1cac6eef8e84d08434b726e39616a0b627c60be/mkdocs_git_revision_date_localized_plugin/util.py#L102-L122 --> mkdocs_git_revision_date_localized_plugin is using 'author date' also (https://git-scm.com/docs/git-log#Documentation/git-log.txt-ematem).

I think 'author date' refers to the date a commit touched a certain file 'authored'. I suspect the issue is that there are multiple commits, and you'll need to select the latest (or first).

Here's how mkdocs-git-revision-date-localized-plugin implements it:

# Latest commit touching a specific file
commit_timestamp = git.log(
    realpath, date="short", format="%at", n=1
)

Or first commit:

# diff_filter="A" will select the commit that created the file
commit_timestamp = git.log(
    realpath, date="short", format="%at", diff_filter="A"
)
# A file can be created multiple times, through a file renamed. 
# Commits are ordered with most recent commit first
# Get the oldest commit only
if commit_timestamp != "":
    commit_timestamp = commit_timestamp.split()[-1]

The format you're using is different:

https://github.com/fralau/mkdocs_macros_plugin/blob/4711e989af1ab0ed86805941f6153c68e88a8ef6/mkdocs_macros/context.py#L138

But reading the documentation that should be fine:

%at
author date, UNIX timestamp

%ai
author date, ISO 8601-like format

%aI
author date, strict ISO 8601 format

Hope this helps!

[Kryptos-FR]

Thanks a lot. I am not a specialist of git, so this is well received.

Could you refer me to some git documentation where this question is covered?

Basically by default the person that creates a commit is both the author and the committer and thus both dates and authors are the same. However, sometimes a commit is cherry-picked from one branch to another, in which case the original date and author of the commit is different from the last committer and date of that cherry-picked commit.

It is referenced in this documentation page: https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History

You may be wondering what the difference is between author and committer. The author is the person who originally wrote the work, whereas the committer is the person who last applied the work. So, if you send in a patch to a project and one of the core members applies the patch, both of you get credit — you as the author, and the core member as the committer.

In your case here, it is simpler a matter of selecting the proper "pretty" format, to display one of the other.

Specifier	Description of output
%an	Author name
%ae	Author email
%ad	Author date (format respects the --date=option)
%cn	Committer name
%ce	Committer email
%cd	Committer date

[fralau]

@Kryptos-FR and @timvink Could you let me know if the new version works for you? If it does, I will deploy it.

[timvink]

@timvink Could you let me know if ...

Tbh I'm currently not using this plugin in any of my projects, so don't have a project to test it on.

[Kryptos-FR]

@fralau works for me.

$ git log --format=fuller -1
commit ecf0069f04fdf65de1de05bfe1e5e8944c85bee6 (HEAD -> main)
Author:     Nicolas Musset <redacted@mail.com>
AuthorDate: Sun Jan 9 17:13:06 2022 +0100
Commit:     Nicolas Musset <redacted@mail.com>
CommitDate: Thu Jan 27 13:01:22 2022 +0100

Then on the doc page it displays: From this code:

Built on {{ (git.date or now()).strftime("%b %d, %Y at %H:%M:%S") }}{% if git.status %} from commit [{{ git.short_commit }}](https://github.com/organization/repository/commit/{{ git.commit }}) by {{ git.author }}{% endif %}.

[fralau]

Thanks for the feedback.