Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Include link to git commit SHA used to compile pdf in LaTeX

Automatically include link to current git commit/SHA in compiled LaTeX pdf

This code lets you include an automatically updating link in a LaTeX compiled document that points to the last commit in the branch currently checked out in the repository where the .tex file used to compile the documents is saved. This allows you to track exactly which version of your .tex file was used to generate a given PDF.

Using Git you can then go back to the exact code used when compiling any saved or printed version of your document you find, no matter how long ago it was compiled. The commit SHA (the unique commit ID) will automatically update each time there is a new commit when you re-compile your document, without other any manual tasks required.

The commit it links to is the most recent commit to the repository regardless if that specific commit modified your .tex file or not. That commit may have modified a script in the same repository that generated tables included in the .tex file. It could also have modified files in the same repository completely unrelated to your .tex file, like a README.md file. You can still use GitHub's tools at any point in the future, to navigate to the version of the .tex file at the time of that commit, even if that commit did not modify your .tex file.

Example

We include this in the copyright page of the book we are writing. Using this we will always know the exact set of .tex files that was used to generate any printed or PDF copy of the book we ever come across. The image below shows the bottom of the copyright page. See the last line of this page. The link in the image can be clicked here. Then you can click the Browse files button and browse all files in the repository exactly how they were when the document was compiled.

image

Setup

See example.tex (in this gist) for an example on how to set it up. There are only two modifications you need to make. \newcommand{\gitfolder}{.git} and \newcommand{\reponame}{worldbank/d4di}.

If your .tex file is in the top-level folder in your repository, then there you do not need to change the \gitfolder value. If your .tex file is in a sub folder then you need to change it to \newcommand{\gitfolder}{../.git}, if it is in a sub-sub folder then you have to change it to \newcommand{\gitfolder}{../../.git} etc. Secondly, you also need to change \newcommand{\reponame}{worldbank/d4di} to the account name and the repo name for your repo so that the full URL is correct. Once you have done that, you can use the macro \commiturl anyhere you want the link in your document to the most recent commit.

How it works

In the repo clone on your computer there is a hidden folder called .git in the top-level folder of your repository. You might not see this folder if the setting on your computer is to not show hidden files, but it is still there. You should never manually edit anything in this folder, but if you were to look you would find meta-information about your repository there.

In the .git folder there is one file called HEAD (see graph below where only relevant files and folders are included). The only content in that file is a one line string that shows which branch you currently have checked out. The format of that string is ref: refs/heads/master if you currently have the master branch checked out. The second part of that string is relative path in your .git folder where the file that list the sha of the last commit in that branch.

This LaTeX code simply follows those steps to get the commit sha, and together with the repo name and the name of the account that owns the repo, it creates a URL to the commit checked out when compiling that version of the document.

.git              <- folder
|-refs            <- folder
| |-heads         <- folder
|   |-master      <- file with the sha of most recent commit for branch master
|   |-branch1     <- file with the sha of most recent commit for branch branch1
|   |-branch2     <- file with the sha of most recent commit for branch branch2
|-HEAD            <- file with "ref: refs/heads/branch1" if branch1 is currently checked out
texfolder         <- folder
|-example.tex     <- location in the project folder assumed the example.tex file in this gist

Warnings

The commit that will be pointed to is the most recent commit. Any uncommitted edits you have will not be included. The commit does not need to be pushed to the cloud (for example to GitHub.com).

\documentclass{report}
% Two required libraries
\usepackage{xstring}
\usepackage{catchfile}
% Set user input
\newcommand{\gitfolder}{.git} % Relative path to .git folder from .tex file
\newcommand{\reponame}{worldbank/d4di} % Name of account and repo. Will be included in URL
% Based on this https://tex.stackexchange.com/questions/455396/how-to-include-the-current-git-commit-id-and-branch-in-my-document
\CatchFileDef{\headfull}{\gitfolder/HEAD}{} % Get path to head file for checked out branch
\StrGobbleRight{\headfull}{1}[\head] % Remove end of line character
\StrBehind[2]{\head}{/}[\branch] % Parse out the path only
\CatchFileDef{\commit}{\gitfolder/refs/heads/\branch}{} % Get the content of the branch head
\StrGobbleRight{\commit}{1}[\commithash] % Remove end of line character
% Build the URL to this commit based on the information we now have
\newcommand{\commiturl}{\url{https://github.com/\reponame/commit/\commithash}}
\begin{document}
Compiled from commit \commiturl
\end{document}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment