How to manage the version number in Git?

Question

Let's imagine the blerp command line tool maintained on git. This tool has the (hidden) --version option which returns its version (let's say 0.1.2) and another --commit which returns the commit number from which it was built.

Both the version and the commit number are hard-coded on the code base.

Now I make a bugfix then commit and rebuild my program. I will still see 0.1.2 although this new version differ from the original 0.1.2. Only the commit will tell me that it is not the same 0.1.2. Is that bugfix worth a different version number?

One solution is that each time I make a commit, I increase the hard-coded version number (which implies to always modify a minimum of 2 files for each commit). This is a binding solution and it does not work when the developers are working on different active branches. If Bob works on feature foo from the version 0.1.2 and Alice works on feature bar from the same version. How do they increase their version number? Bob can use the odd and Alice the even. What if Eve works on a third feature?

Another solution can be to use the Git tags to automatically generate the version number. A script can find the closest tag starting with v such as v0.1.2 and use the tag name as the version number plus the first n digits of the current commit (v0.1.2 (build 4acd21)). This works well if the working directory is clean. One can imagine to add a * before the build number to indicate the working directory is not clean. The main problem with this solution is if somebody export the sources, it won't be able to build blerp.

What possible alternative can solve this issue?

Answer 1

Alexey Kiselev and Dario already hinted towards the answer, but I will try to explain it in detail.

Versioning Schemes

There are two types of versioning schemes:

1. Internal version number: This can be incremented many times in a day (e.g. revision control number)
2. Released version: This changes less often (e.g. semantic versioning)

People use different schemes as per their need, but semantic versioning is fairly widely used and authored by Tom Preston-Werner, co-founder of GitHub.

Semantic Versioning

Semantic versioning follows the pattern of X.Y.Z

Or more readable would be [major].[minor].[patch]-[build/beta/rc]

E.g. 1.2.0-beta

major or X can be incremented if there are major changes in software, like backward-incompatible API release.

minor or Y is incremented if backward compatible APIs are introduced.

patch or Z is incremented after a bug fix.

How do we achieve this using Git?

By using tags:

Tags in Git can be used to add a version number.

git tag -a "v1.5.0-beta" -m "version v1.5.0-beta"

adds a version tag of v1.5.0-beta to your current Git repository. Every new commit after this will auto-increment tag by appending commit number and commit hash. This can be viewed using the git describe command.

v1.5.0-beta-1-g0c4f33f here -1- is the commit number and 0c4f33f the abbreviation of commit's hash. The g prefix stands for "git".

Complete details can be viewed using:

git show v1.5.0-beta