Add ability to show tag/commit/dirty

[keiranmraine]

This is a great tool to show users when the docs were last updated, but it would be exceptionally helpful to be able to embed the version/tag if available, falling back to head commit and an indicator if the workspace is dirty.

The examples below can only be attempted after confirming .git exists.

e.g.

# repo with no tags and dirty workspace
$ GIT_REV=$(git describe --dirty || (git show --format="%h" --no-patch | tr -d '\n' && git diff --quiet || echo '-dirty'))
fatal: No names found, cannot describe anything.
$ echo $GIT_REV
27d95e8-dirty

# repo with tags
$ GIT_REV=$(git describe --dirty || (git show --format="%h" --no-patch | tr -d '\n' && git diff --quiet || echo '-dirty'))
$ echo $GIT_REV
2.1.1-1-g50fabe3

## with tags and dirty
$ GIT_REV=$(git describe --dirty || (git show --format="%h" --no-patch | tr -d '\n' && git diff --quiet || echo '-dirty'))
$ echo $GIT_REV
2.1.1-1-g50fabe3-dirty

# with tag checked out
$ GIT_REV=$(git describe --dirty || (git show --format="%h" --no-patch | tr -d '\n' && git diff --quiet || echo '-dirty'))
$ echo $GIT_REV
2.1.0

[timvink]

Not a bad idea. We're accessing git info anyway, and might as well expose a couple of extra variables from git while we're at it. Although it's clearly beyond the scope of the revision date. I've been hesitant to add more git info before, as there's overlap with mkdocs-git-authors-plugin for example. But I now see them as slightly more specialized git plugins; this one around dates, the other making it easier to add git authors to the site.

Currently, we have this list: https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/available-variables/ . Adding some extra git variables for developers to use while extending their themes doesn't hurt ease of use for normal users, doesn't hurt performance and makes certain customizations easier.

Would you be willing to make a PR ?

[timvink]

Btw, came across this plugin which is related: https://github.com/agarthetiger/mkdocs_latest_release_plugin

[thatlittleboy]

Hi, I stumbled upon this issue when looking for a similar functionality -- I too, would like to display git SHA corresponding to the current mkdocs site build (useful for tracing back to what the state of the repository is when the doc was generated).

I think it is tangentially related to "git revision date" (as a git SHA does correspond to a particular repository state at a particular point in time). More so than git authors/committers, at least :)

I take it from the previous reply in the thread that this change is still welcome? @timvink I could try to formulate a PR if so.

[timvink]

Hi @thatlittleboy, I appreciate the offer!

There are quite some plugins that retrieve information from the .git folder. I maintain both this plugin and https://github.com/timvink/mkdocs-git-authors-plugin, and I know of more plugins that extract git info. That means the same logic is reimplemented multiple times. I've already realized there are quite a number of edge cases (I would have never imaged the amount the fixes and changes this plugin has received over time, as it's all quite simple at its core).

I've started work on a new plugin, https://github.com/timvink/mkdocs-git-info-plugin, which will take care of extracting all the relevant git info and exposing all the git variables. With mkdocs 1.4 it becomes much easier to share state across plugins, so this plugin can be used by other plugins also.

I still need to design how the variables will be stored, but once the design is there, I'll create some issues and would appreciate any help there.

The whole thing is a low-priority hobby project so don't expect big things soon ;)