Git Versioner Maven Extension

Maven projects are usually versioned in pom.xml by manipulating version tags. This may require a manual changes to the file. Git Versioner Maven Extension can use the git commit messages to auto-calculate a Semantic Version for the project.

Let’s look at how we can use this module for Maven projects.

Configuration

Git Versioner Maven Extension is a Maven Build Extension that can participate in Maven’s build lifecycle. To add this extension to Maven project, Create (or modify) ${project.baseDir}/.mvn/extensions.xml with following entry -

.mvn/extensions.xml
<extensions xmlns="http://maven.apache.org/EXTENSIONS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/EXTENSIONS/1.0.0 https://maven.apache.org/xsd/core-extensions-1.0.0.xsd">

    <extension>
        <groupId>com.github.manikmagar</groupId>
        <artifactId>git-versioner-maven-extension</artifactId>
        <version>0.9.2</version>   (1)
    </extension>

</extensions>
1 Latest versions are available on Maven Central

With just that configuration, next time you run any maven goals on the project, Maven uses the artifact version generated by this extension instead of the one defined in project pom.

Project must have a local Git repository initialized.

To check the maven artifact version, you can simply run below command to print version on command line -

shell
mvn help:evaluate -Dexpression=project.version -q -DforceStdout

How does it work?

The extension iterates over all the commit history and looks for predefined keywords representing version changes. It then computes the version number upto current commit.

Version keywords are the reserved words that describes which milestone of the release is this.

By default, extension supports following keywords -

  • [major] - A Major version milestone Eg. 1.0.0 → 2.0.0

  • [minor] - A Minor version milestone Eg. 1.1.0 → 1.2.

  • [patch] - A Patch version milestone Eg. 1.1.1 → 1.1.2

How to increment the version?

Now that you have extension configured, you can continue with your regular development.

When it is time to increment version you can just add a commit with appropriate version keyword.

Version commit
git commit --allow-empty -m "chore: [<keyword>] release" (1)
1 where <keyword> can be one of these - major, minor, or patch.

Increment with maven goals

The easy way is to use one of the following three goals provided by extension to add an empty commit with appropriate Version Keyword -

  • git-versioner:commit-major: Adds a git commit with a commit message containing Major version keyword

  • git-versioner:commit-minor: Adds a git commit with a commit message containing Minor version keyword

  • git-versioner:commit-patch: Adds a git commit with a commit message containing Patch version keyword

Commit patch
mvn git-versioner:commit-patch --non-recursive
Use --non-recursive flag when running commit goal in a multi-module maven project to avoid adding one commit per module.

How to start with a different version?

When adapting to this extension for previously released projects, you can configure the initial version to start counting from previously released version number. Add following properties (with appropriate values) to .mvn/git-versioner.extensions.properties file -

.mvn/git-versioner.extensions.properties
gv.initialVersion.major=1
gv.initialVersion.minor=3
gv.initialVersion.patch=4

With above initial version configuration, the next version calculated by this extension will be -

  • Major: 2.0.0

  • Minor: 1.4.0

  • Patch: 1.3.5

How to create Git tags?

You can use git-versioner:tag goal to create a git tag for current version in local git repository.

This does not push tag to remote repository.
Create local Git tag
mvn git-versioner:tag

Demo

Conclusion

In this article we looked at how to generate Maven project versions from git commit history and avoid manual version management in the project pom.xml.

Further Reading

The extension supports customization of version keywords, initial versions, tag or commit messages, and even the generated version string formats. See project README on GitHub.

on twitter to get updates on new posts.
Get Started with DataWeave
Getting Started with Maven Build Cache Extension

Stay updated!

On this blog, I post articles about different technologies like Java, MuleSoft, and much more.

You can get updates for new Posts in your email by subscribing to JavaStreets feed here -


{ Manik Magar }

Lives on Java Planet, Walks on Java Streets, Read/Writes in Java, JCP member, Jakarta EE enthusiast, MuleSoft Integration Architect, MuleSoft Community Ambassador, Open Source Contributor and Supporter, also writes at Unit Testers, A Family man!