Easily Calculate Your Project Version With Git

One Problem

Having a good project naming convention and tooling is not as easy as it could or should be. One trying to establish such a policy should take care of several needs:

• Be compliant with the tooling (Maven, Gradle, ...).

• Follow standards when it matters: semver, for example, in regards of version naming.

• Be compatible with good CI pratices (work in branch, CI tests & integration, ...).

• Do not pollute the code base (yes I'm looking at you maven-release-plugin with your several commits and builds!).

• Be flexible to adapt to one's needs.

In the past month, I have seen attempts from people trying to use Git core functionalities to achieve flexible or automatic project version naming.

Most of those attempts are based on 'git describe'. One real drawback of 'git describe', making it useless, is that it is not semver compliant. If you use it to name your project versions, then you will first name your project with `1.0.0` by tagging it and a commit later your project will be `1.0.0-1`. Unfortunately, in semver and more or less in all build tools, 1.0.0-1 < 1.0.0 which is not what you get with 'git describe'.

Still, the idea looks good. We want our project to take one particular commit and label that with a version name. We do not want to have to modify our codebase just to label and tag our codebase.

One Answer

With this in mind, I created the project jgitver and it's associated plugins for the two major build tools I use: Maven (with jgitver-maven-plugin) and Gradle (with gradle-jgitver-plugin).

Instead of writing hundreds of lines, let's just have a look at what those library/plugins offer via some animated GIFs.

When used with default Maven mode:

When used with default Gradle mode:

By using jgitver you have an automatic consistent project naming scheme that does not pollute your git history, is compatible with branches and CI (no multiple deployment of the same version name coming from multiple branches), and is fully controlable (via lightweight or annotated tags and plugin parameters).

Then you will discover that jgitver usage opens up new pathways for your release workflows. No more need to change your projects files to release your project. Release is reduced to the strict minimum that it should always have been:

• Tag or label a commit your are satisfied with.

• Deploy or use the build result to any repository (private/public/...) you need.

And that's all! no need to modify the project version twice and pollute your project history, and no need to use cumbersome and error prone plugins (once again I'm looking at you, maven-release-plugin).

Usage

The usage is very convenient and just requires the plugins to be declared in your build files.

Maven Usage

<build>
    <extensions>
        <extension>
            <groupId>fr.brouillard.oss</groupId>
            <artifactId>jgitver-maven-plugin</artifactId>
            <version>0.1.0</version>
        </extension>
    </extensions>
</build>

Gradle Usage

plugins {
  id "fr.brouillard.oss.gradle.jgitver" version "0.2.0"
}

Of course both plugins can be adapted and configured to meet other needs.

Project Links and Documentation

For more details and configuration options follow the documentation of both projects:

• jgitver-maven-plugin: https://github.com/jgitver/jgitver-maven-plugin

• gradle-jgitver-plugin: https://github.com/jgitver/gradle-jgitver-plugin

• jgitver library: https://github.com/jgitver/jgitver

Feel free to comment or email me about the projects and the needs they try to cover.

I'd be very thankful for every comment on the subject and any new idea that could pop up from any discussion.

Note: jgitver-maven-plugin works with all major IDEs, but due to IDEA-155733, a very recent version of IntelliJ is required (version > 145.1616.11).