Git Versioner Maven Plugin

Generate the semver version using the git commit history and automatically set it to maven pom.

No more manually modifying the pom.xml to decide on the versions. You continue developing and adding commits to your project. When it is time to release, add a commit with a message containing a specific version keyword and watch the magic happen.

Table of Contents

• How does it work?
• What are version keywords?
• How to configure?
• How to start with a different version?
• How do I increment version?
• How to change the version pattern?
• How to customize version keywords?
  • Use regex for version keywords
• How to access generated version properties?
• How to create Git tags?
• Contributing
• Acknowledgement

How does it work?

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

The extension supports generating Semantic Versions x.y.z format. The format pattern is configurable to use values such as Git hash, branch name etc.

See manikmagar/git-versioner-maven-extension-examples for examples of using this extension.

What are version keywords?

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

To change the keywords, see how to Customize Version Keywords.

How to configure?

This is a maven build core extension that can -

• Participate in maven build lifecycle

• Automatically set the building project’s version

• No explicit mojo executions needed to set the version

• Project’s POM remain unchanged

To use as a maven build extension,

Create (or modify) extensions.xml file in ${project.baseDir}/.mvn/ to have the following entry -

📎	The artifact id is git-versioner-maven-extension.

.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>${latest-version-here}</version>
    </extension>

</extensions>

See an example test project at git-versioner-maven-extension/src/test/resources/project-with-extension/.

With just that configuration, next time your project runs any maven goals, you should see version from this module is used by Maven reactor. Try running mvn package on your project.

How to start with a different version?

It is possible that your project is already released with a certain version. In that case, you can configure the initial version to start counting versions from.

You can add following properties to .mvn/git-versioner.extensions.properties file -

Example configuration for initial version for extension mode

gv.initialVersion.major=1
gv.initialVersion.minor=3
gv.initialVersion.patch=4

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

• Major: 2.0.0

• Minor: 1.4.0

• Patch: 1.3.5

How do I increment version?

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

When it is time to increment version, you may use one of the following three goals 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

🔥	Use --non-recursive flag when running commit goal in a multi-module maven project to avoid adding one commit per included module.

The default message pattern is chore(release): [%k] where [%k] is the keyword token. To change the default message pattern, you could pass -Dgv.commit.message=<message> argument when running the goal.

📎	When this extension is configured, it automatically makes git-versioner plugin goals available with NO any additional configuration.

Example commit patch with a custom message

mvn git-versioner:commit-patch "-Dgv.commit.message=chore: [%k] release" --non-recursive

Off course, you can also add commits manually with appropriate version keywords.

Manually adding a version commit

git commit --allow-empty -m "chore: [<keyword>] release" // (1)

1. where <keyword> can be one of these - major, minor, or patch.

How to change the version pattern?

The default version pattern used is major.minor.patch(-commit) where (-commit) is skipped if commit count is 0.

This pattern can be canged by setting a property in .mvn/git-versioner.extensions.properties.

The following example will generate versions as major.minor.patch+shorthash, eg. 1.2.3+a5a29f8.

Example configuration for version pattern in extension mode

gv.pattern.pattern=%M.%m.%p+%h

Table 1. Available Tokens for Version Pattern

Token	Description	Example
%M	Major Version	1.y.z
%m	Minor Version	x.1.z
%p	Patch Version	x.y.1
%c	Commit count	x.y.z-4
([anything]%c)	Non-Zero Commit count	Given %M.%m.%p(-%c) with %M=1, %m=2, %p=3 when c == 0 → 1.2.3 when c > 0, = 5 → 1.2.3-5
%b	Branch name	%M.%m.%p+%b → 1.2.3+main
%H	Long Hash Ref	%M.%m.%p+%H → 1.2.3+b5f600c40f362d9977132e8bf7398d2cdc745c28
%h	Short Hash Ref	%M.%m.%p+%H → 1.2.3+a5a29f8

How to customize version keywords?

The default version keywords [major], [minor], and [patch] can be customized by overriding the configuration.

To use different keywords, you can add following properties to .mvn/git-versioner.extensions.properties file -

Example configuration for initial version for extension mode

gv.keywords.majorKey=[BIG]
gv.keywords.minorKey=[SMALL]
gv.keywords.patchKey=[FIX]

Use regex for version keywords

You can also use regex to match version keywords. This is useful when you want to be sure that the version keyword will only be matched when it is the first word in the commit message. So if for example you have a merge commit message which contains the messages of the merged commits, you can use a regex to match only the first commit message.

To use regex for version keywords, you can add following properties to .mvn/git-versioner.extensions.properties file -

Example configuration for regex version keywords

gv.keywords.useRegex=true
gv.keywords.majorKey=^\\[major\\].*
gv.keywords.minorKey=^\\[minor\\].*
gv.keywords.patchKey=^\\[patch\\].*

How to access generated version properties?

This extension adds all version properties to Maven properties during build cycle -

Example of Injected maven properties (demo values)

git-versioner.commitNumber=0
git-versioner.major=0
git-versioner.minor=0
git-versioner.patch=1
git-versioner.version=0.0.1
git.branch=main
git.hash=67550ad6a64fe4e09bf9e36891c09b2f7bdc52f9
git.hash.short=67550ad

You may use these properties in maven pom file, for example as ${git.branch} to access git branch name.

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.

Tag goal with default parameter values

mvn git-versioner:tag \
  "-Dtag.failWhenTagExist=true" \
  "-Dtag.messagePattern=Release version %v" \
  "-Dtag.namePattern=v%v"

For Tag goal, it is possible to configure pom.xml to contain the git-versioner plugin with required execution configuration.

Git Tag Goal with default configuration parameters

<plugin>
    <groupId>com.github.manikmagar</groupId>
    <artifactId>git-versioner-maven-plugin</artifactId>
    <executions>
      <execution>
        <id>tag</id>
        <goals>
          <goal>tag</goal>
        </goals>
        <configuration>
          <failWhenTagExist>true</failWhenTagExist> // (1)
          <tagNamePattern>v%v</tagNamePattern>  // (2)
          <tagMessagePattern>Release version %v</tagMessagePattern> // (3)
        </configuration>
      </execution>
    </executions>
</plugin>

1. If set to not fail, it will just log warning and skip tag creation.

2. Tag name pattern to use. Default v%v will result in tags like v1.2.3.

3. Tag message pattern to use. Default Release version %v will add tag message like Release version 1.2.3.

Contributing

All contributions are welcome. Please see Contributing guides.

Acknowledgement

This is inspired from Gradle plugin toolebox-io/gradle-git-versioner that I have been using for my Gradle projects. This maven plugin is my attempt to get those auto-version capabilities into my Maven builds.