Increase version number automatically with git

It has been a while since I started using git and, honestly, it has become an essential tool in my daily routine. It does not matter whether I am working solo or in a larger team, git is invaluable to track the changes in my work, orchestrate the collaboration with my peers and support the deployment to different environments.

In this article, I would like to introduce a quick and simple way to update the version number automatically every time you commit your work. If you are a researcher, this typically involves source code, \(\LaTeX\) documents, small datasets, web pages and potentially anything else (wait… because you version your \(\LaTeX\) documents, don’t you?).

While git is a powerful and versatile tool, I am not covering here the different possible workflows, such as the git flow, GitHub flow or GitLab flow to name a few. Neither am I discussing the versioning schemes, such as semantic versioning or PEP 440 for Python. In fact, depending on your needs, you may require more comprehensive solutions such as the full-fledged GitVersion. Conversely, the script below is just a quick hack that keeps track of a “commit number” that is increased automatically every time you commit (either by command-line or clicking the appropriate button in the git client of your choice). The idea is to place this number somewhere meaningful and display it prominently, so everyone may quickly identify which version of your work is at play (e.g. header of a scientific paper, the output of a computer program, the footer of a web page and so on).

Step 1: pick the file to update automatically

Having said that, let’s imagine that our project consists of source code in Python. This is not a requirement, though, because adapting to any other file format is very easy as we will see below. So in this example we have a Python package containing the usual __init__.py file that looks like this:

# version number
MAJOR = 1
MINOR = 14
PATCH = 3
COMMIT = XXX  # updated automatically
__version__ = f'{MAJOR}.{MINOR}.{PATCH} (commit #{COMMIT})'

As you may have noticed, the goal is to build a string that concatenates the major, minor, patch and commit numbers that make the version. The first three fields are widely used in semantic versioning and must be set manually in the file. However, the commit number will be generated automatically by a script that will overwrite that specific line. Note that a “commit number” (i.e. how many commits the repo contains) is not the same as a “build number” (i.e. how many times you built the product). For example, under some circumstances, if you use CI/CD pipelines such as the ones available in GitHub or GitLab, a commit might trigger a new build. Still, it is perfectly fine if they are completely unaligned.

Step 2: the git hook

Perhaps one of the most overlooked git features by regular users is the possibility of executing scripts when specific actions occur. These scripts are named “hooks”, and git automatically place some examples in the .git/hooks directory inside every repository. Feel free to have a look and customize them to fit your needs, and remember to remove the .sample from the filename to enable them. You may need to grant execution permissions as well (use chmod u+x if required). Be aware that there are client-side and server-side hooks, and that they are not automatically copied when the repository is cloned. Consequently, you will have to install them manually if you deploy a repository elsewhere.

In this case, we are customizing the post-commit client-side hook with a bash script suitable for Linux and macOS systems. It is also feasible to use any other scripting language supported by your operating system, such as Python.

#!/bin/bash

# count number of commits
NUMBER=`git rev-list --all --count`

# replace line starting with COMMIT with a new one which contains the actual commit number
sed -i '' "s/^COMMIT.*$/COMMIT = $NUMBER/g" src/package/__init__.py

The script above will be triggered automatically every time you commit. The first part retrieves the total number of commits in the repository by listing them with git rev-list. Next, it uses sed to find the line that starts with COMMIT and then replace it with COMMIT = number. Unfortunately, the syntax might not look straightforward, but this is the way that regular expressions work. The end of the statement is the path to the file where the replacement must take place. To adapt it to your needs, adjust the text to be updated and fix the path in the last line of the script.

After every successful commit, the script will increase the commit number and update the source file accordingly. As a result, if you display the version somewhere noticeable such as the header of a document, the top cell of a jupyter notebook or during a program start-up, everybody will always be aware of which version they are using. It is also very motivating to see the commit number grow, reflecting the effort invested in the project.

Summary

In this article, we have learnt to update automatically the version number of almost any piece of work under git control. This procedure is pretty straightforward and only requires a script with a couple of lines, so there are no excuses to give it a try! Even so, should you have more demanding needs, rest assured that there are comprehensive solutions out there that offer much broader functionality. I hope this little tip helps to boost your productivity. Please feel free to comment and keep posted for more articles!