This plugin allows to define the pom version of your project using the information from your git history.
It calculates the version, a little bit like git describe would do but in a more efficient way for maven projects:
- new commits have upper version than previous commit (in the way maven/semver interpret versions)
- version calculation is based on git tags & branches
- git lightweight tags allow for intermediate version controlling between releases
- allow to define what is the next version pattern to use
- minimal setup via maven extension
Here is an illustration of the capabilities of the plugin
Since version 0.3.0 jgitver-maven-plugin needs to be run as a maven core extension.
The installation scripts below will use the latest version available ; if you are updating find the latest version here or there.
via curl
from the root directory of your project, run:
sh -c "$(curl -fsSL https://raw.githubusercontent.com/jgitver/jgitver-maven-plugin/master/src/doc/scripts/install.sh)"via wget
from the root directory of your project, run:
sh -c "$(wget https://raw.githubusercontent.com/jgitver/jgitver-maven-plugin/master/src/doc/scripts/install.sh -O -)"manually
-
Create a directory
.mvnunder the root directory of your project. -
Create file
.mvn/extensions.xml -
Put the following content to
.mvn/extensions.xml(adapt to latest version).<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 http://maven.apache.org/xsd/core-extensions-1.0.0.xsd"> <extension> <groupId>fr.brouillard.oss</groupId> <artifactId>jgitver-maven-plugin</artifactId> <version>1.8.0</version> </extension> </extensions>
In order to control jgitver-maven-plugin behavior, you can provide a configuration
file under $rootProjectDir/.mvn/jgitver.config.xml.
The configuration file must be compliant with the latest jgitver-configuration-v1_1_0.xsd xml schema.
Here is an example configuration file:
<configuration xmlns="http://jgitver.github.io/maven/configuration/1.1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://jgitver.github.io/maven/configuration/1.1.0 https://jgitver.github.io/maven/configuration/jgitver-configuration-v1_1_0.xsd">
<mavenLike>true/false</mavenLike> <!-- deprecated, use 'strategy' instead -->
<strategy>MAVEN|CONFIGURABLE|PATTERN</strategy>
<policy>MAX|LATEST|NEAREST</policy> <!-- LookupPolicy to select the base tag/commit for the version computation -->
<autoIncrementPatch>true/false</autoIncrementPatch>
<useCommitDistance>true/false</useCommitDistance>
<useDirty>true/false</useDirty>
<useGitCommitId>true/false</useGitCommitId>
<useSnapshot>true/false</useSnapshot> <!-- use -SNAPSHOT in CONFIGURABLE strategy -->
<gitCommitIdLength>integer</gitCommitIdLength> <!-- between [8,40] -->
<maxSearchDepth>integer</maxSearchDepth> <!-- upper or equal to 1, ommited otherwise, default to infinite -->
<nonQualifierBranches>master</nonQualifierBranches> <!-- comma separated, example "master,integration" -->
<regexVersionTag>r([0-9]+)</regexVersionTag> <!-- a java regular expression with a capture group matching only
tags of the form r0, r1, ..., r34-->
<exclusions> <!-- Optional list of directory path -->
<exclusion>relative directory path</exclusion> <!-- relative path from project root directory -->
</exclusions>
<useDefaultBranchingPolicy>true/false</useDefaultBranchingPolicy> <!-- uses jgitver#BranchingPolicy#DEFAULT_FALLBACK as fallback branch policy-->
<branchPolicies>
<branchPolicy>
<pattern>pattern</pattern> <!-- regex pattern -->
<!-- list of transformations to apply, if empty, defaults to REPLACE_UNEXPECTED_CHARS_UNDERSCORE, LOWERCASE_EN -->
<transformations>
<transformation>NAME</transformation> <!-- transformation name, one of jgitver#fr.brouillard.oss.jgitver.BranchingPolicy#BranchNameTransformations -->
...
</transformations>
</branchPolicy>
...
</branchPolicies>
</configuration>Please consult jgitver documentation to fully understand what the parameters do.
Old xml schemas are kept for reference.
-Djgitver.skip=true: skips totally jgitver usage-Djgitver.config=FILE: overrides default config file and uses FILE instead-Djgitver.use-version=VERSION: execute jgitver but finally uses VERSION as the project version-Djgitver.resolve-project-version=true: replaces the ${project.version} also in properties, dependencies, dependencyManagement, plugins and pluginManagement sections-Djgitver.export-properties-path=FILE: exports output properties into the given file
When working on a detached HEAD, no branch information exists anymore from git.
Since 1.3.0 it now possible to provide externally the branch information via a system property or an envrionement variable.
-Djgitver.branch=SOME_BRANCH_NAMEJGITVER_BRANCH=SOME_BRANCH_NAME && mvn validatefor bash like shellsSET JGITVER_BRANCH=SOME_BRANCH_NAME
mvn validate
for windows CMD (I don't know a one liner solution)
The plugin exposes git calculated properties available during the maven build.
Those are available under the following properties name: "jgitver.meta" where meta is one
of Metadatas name in lowercase
in addition to jgitver.used_version which represents the version ultimately
applied (in case it was overriden on the command line using -Djgitver.use-version=VERSION).
You can then use them as standard maven properties in your build:
<plugin>
<artifactId>maven-antrun-plugin</artifactId>
<executions>
<execution>
<phase>validate</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<tasks>
<echo>used version: ${jgitver.used_version}</echo>
<echo>version calculated: ${jgitver.calculated_version}</echo>
<echo>dirty: ${jgitver.dirty}</echo>
<echo>head_committer_name: ${jgitver.head_committer_name}</echo>
<echo>head_commiter_email: ${jgitver.head_commiter_email}</echo>
<echo>head_commit_datetime: ${jgitver.head_commit_datetime}</echo>
<echo>git_sha1_full: ${jgitver.git_sha1_full}</echo>
<echo>git_sha1_8: ${jgitver.git_sha1_8}</echo>
<echo>branch_name: ${jgitver.branch_name}</echo>
<echo>head_tags: ${jgitver.head_tags}</echo>
<echo>head_annotated_tags: ${jgitver.head_annotated_tags}</echo>
<echo>head_lightweight_tags: ${jgitver.head_lightweight_tags}</echo>
<echo>base_tag: ${jgitver.base_tag}</echo>
<echo>all_tags: ${jgitver.all_tags}</echo>
<echo>all_annotated_tags: ${jgitver.all_annotated_tags}</echo>
<echo>all_lightweight_tags: ${jgitver.all_lightweight_tags}</echo>
<echo>all_version_tags: ${jgitver.all_version_tags}</echo>
<echo>all_version_annotated_tags: ${jgitver.all_version_annotated_tags}</echo>
<echo>all_version_lightweight_tags: ${jgitver.all_version_lightweight_tags}</echo>
</tasks>
</configuration>
</execution>
</executions>
</plugin>resulted in my case
[INFO] Executing tasks
[echo] used version: 0.2.0-SNAPSHOT
[echo] version calculated: 0.2.0-SNAPSHOT
[echo] dirty: true
[echo] head_committer_name: Matthieu Brouillard
[echo] head_commiter_email: [email protected]
[echo] head_commit_datetime: Thu Jun 30 14:06:14 2016 +0200
[echo] git_sha1_full: fadd88e04b25c794cea876b03d8234df5bf4e37b
[echo] git_sha1_8: fadd88e0
[echo] branch_name: master
[echo] head_tags:
[echo] head_annotated_tags:
[echo] head_lightweight_tags:
[echo] base_tag: v0.2.0
[echo] all_tags: v0.2.0,0.1.1,0.1.0,0.0.3,0.0.2,0.0.1
[echo] all_annotated_tags: 0.1.1,0.1.0,0.0.3,0.0.2,0.0.1
[echo] all_lightweight_tags: v0.2.0
[echo] all_version_tags: v0.2.0,0.1.1,0.1.0,0.0.3,0.0.2,0.0.1
[echo] all_version_annotated_tags: 0.1.1,0.1.0,0.0.3,0.0.2,0.0.1
[echo] all_version_lightweight_tags: v0.2.0
[INFO] Executed tasks
You can also output the properties into a file so that they can be picked
up by the next steps in your build pipeline. This is accomplished by setting
the jgitver.export-properties-path system property, e.g. from the command
line:
mvn ... -Djgitver.export-properties-path=./jgitver-output.properties
The produced file follows the Java Properties standard.
If you want to give it a try you can use the following script that will setup a demo project under /tmp/jgitver-tester
# let's create a fake maven project under /tmp
cd /tmp
mvn archetype:generate -B -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart \
-DarchetypeVersion=1.1 -DgroupId=com.company -DartifactId=jgitver-tester -Dversion=0 -Dpackage=com.company.project
cd jgitver-tester
# init the created project with jgitver-maven-plugin
sh -c "$(wget https://raw.githubusercontent.com/jgitver/jgitver-maven-plugin/master/src/doc/scripts/install.sh -O -)"
# let's do some modifications/commits/tags
echo A > content
git init
git add .
git commit -m "initial commit"
echo B > content && git add -u && git commit -m "added B data"
git tag 1.0 -m "release 1.0"
echo C > content && git add -u && git commit -m "added C data"
git checkout -b cool-feature
echo D > content && git add -u && git commit -m "added D data"
git checkout master
echo E > content && git add -u && git commit -m "added E data"
mvn validate
Then play around with it doing:
mvn validatemvn installgit checkout 1.0mvn validategit checkout cool-featuremvn validate
jgitver-maven-plugin requires at least maven-3.3.2 to work correctly.
Think to modify your IDE settings regarding maven version ; if required do not use the embedded maven version of your IDE but an external one that fulfill the maven minimal requirements.
- Eclipse: tested with Eclipse Mars.2 Release 4.5.2
- Netbeans: tested with NetBeans IDE 8.1 Build 201510222201
- Intellij IDEA: tested with 2016.1.3
see also the Contributing guide.
Before pushing try to always verify that the modifications pushed in MD files will be correctly rendered by Github.
For that purpose you can use grip.
mvn -Prun-its clean install
or using docker
- Linux:
docker run --rm -v $(pwd):/root/sources -w /root/sources maven:3.6.3-openjdk-11 mvn -Prun-its clean install - Windows:
docker run --rm -v %CD%:/root/sources -w /root/sources maven:3.6.3-openjdk-11 mvn -Prun-its clean install - Old linux command:
docker run --rm -v $(pwd):/root/sources -w /root/sources maven:3.6.3-openjdk-11 ./src/ci/build-with-external-it-fallback.sh
build and filter some IT tests
mvn -Prun-its clean install "-Dinvoker.test=issues/issue-36*"
If needed, one can also add in above docker command a volume sharing
with the maven local repository by adding something like -v MLR_LOCATION:/root/.m2/repository for example -v D:\dev\mlr:/root/.m2/repository.
mvn -Poss clean install: this will simulate a full build for oss delivery (javadoc, source attachement, GPG signature, ...)git tag -a -s -m "release X.Y.Z, additionnal reason" X.Y.Z: tag the current HEAD with the given tag name. The tag is signed by the author of the release. Adapt with gpg key of maintainer.- Matthieu Brouillard command:
git tag -a -s -u 2AB5F258 -m "release X.Y.Z, additionnal reason" X.Y.Z - Matthieu Brouillard public key
- Matthieu Brouillard command:
mvn -Poss,release -DskipTests clean deploygit push --follow-tags origin master
Since 1.0.0, it is possible to totally skip the plugin execution by launching maven with the user property jgtiver.skip set to true, example:
mvn clean install -Djgitver.skip=true
If your version is not calculated correctly by maven/jgitver, there are good chances that the plugin is not active.
Please verify that you are using maven >= 3.3.2.
if during a build all the plugins & dependencies are resolved to the exacts same version then chances are high that you have the local maven repository as a subdirectory of your jgitver handled project.
To overcome this problem you have 2 possibilities:
- separate correctly your project from the MLR and make sure the MLR is not a subdirectory of your jgitver managed project
- configure jgitver (using
.mvn/jgitver.config.xml) to ignore your subdirectory MLR, see the configuration paragraph<configuration> <exclusions> <exclusion>path_to_your_mlr</exclusion> <!-- can be .m2, .repository or something else --> </exclusions> </configuration>
see also #90 && #91 for discussions on this topic.
If you develop a maven plugin project, you normally run maven-invoker-plugin to test your plugin.
Using default configuration, maven-invoker-plugin will use a temporary local repository under target/local-repo and the IT tests will be executed from target/it/XYZ.
In this context, when executing tests, maven will try to activate extensions starting from the target/it/XYZ directory ; and it will find your extensions definition in the root directory of the project. This will lead in the activation of jgitver-maven-plugin for all your IT projects AND for the poms inside the temporary local repository under target/local-repository.
To avoid such behavior, you need to tell jgitver-maven-plugin to ignore some directories. If you do not have already a jgitver configuration file, create one under .mvn/jgitver.config.xml and declare some exclusions (see configuration):
<configuration>
<exclusions>
<exclusion>target/local-repo</exclusion>
<exclusion>target/it/**</exclusion>
</exclusions>
</configuration>You can have a look at the configuration of jgitver-maven-plugin itself.
jgitver-maven-plugin is delivered under the Apache Licence, Version 2