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.
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.
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.
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. |
<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.
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 -
gv.initialVersion.major=1
gv.initialVersion.minor=3
gv.initialVersion.patch=4With 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
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.
|
mvn git-versioner:commit-patch "-Dgv.commit.message=chore: [%k] release" --non-recursiveOff course, you can also add commits manually with appropriate version keywords.
git commit --allow-empty -m "chore: [<keyword>] release" // (1)-
where
<keyword>can be one of these - major, minor, or patch.
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.
gv.pattern.pattern=%M.%m.%p+%h| 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 |
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 -
gv.keywords.majorKey=[BIG]
gv.keywords.minorKey=[SMALL]
gv.keywords.patchKey=[FIX]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 -
gv.keywords.useRegex=true gv.keywords.majorKey=^\\[major\\].* gv.keywords.minorKey=^\\[minor\\].* gv.keywords.patchKey=^\\[patch\\].*
This extension adds all version properties to Maven properties during build cycle -
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=67550adYou may use these properties in maven pom file, for example as ${git.branch} to access git branch name.
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. |
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.
<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>-
If set to not fail, it will just log warning and skip tag creation.
-
Tag name pattern to use. Default
v%vwill result in tags likev1.2.3. -
Tag message pattern to use. Default
Release version %vwill add tag message likeRelease version 1.2.3.
All contributions are welcome. Please see Contributing guides.
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.