Repository files navigation

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 likegit 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 thenext version pattern to use
• minimal setup via maven extension

Here is an illustration of the capabilities of the plugin

Since version0.3.0jgitver-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 versionhere orthere.

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

1. Create a directory.mvn under the root directory of your project.

2. Create file.mvn/extensions.xml

3. Put the following content to.mvn/extensions.xml (adapt tolatest version).

   <extensionsxmlns="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 controljgitver-maven-plugin behavior, you can provide a configurationfile under$rootProjectDir/.mvn/jgitver.config.xml.The configuration file must be compliant with the latestjgitver-configuration-v1_1_0.xsd xml schema.

Here is an example configuration file:

<configurationxmlns="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 consultjgitver 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.
Since1.3.0 it now possible to provide externally thebranch information via a system property or an envrionement variable.

• -Djgitver.branch=SOME_BRANCH_NAME
• JGITVER_BRANCH=SOME_BRANCH_NAME && mvn validate for bash like shells
• SET 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" wheremeta is oneofMetadatas name in lowercasein addition tojgitver.used_version which represents the version ultimatelyapplied (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: matthieu@brouillard.fr     [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 pickedup by the next steps in your build pipeline. This is accomplished by settingthejgitver.export-properties-path system property, e.g. from the commandline:

    mvn ... -Djgitver.export-properties-path=./jgitver-output.properties

The produced file follows theJava 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 /tmpcd /tmpmvn 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.projectcd jgitver-tester# init the created project with jgitver-maven-pluginsh -c "$(wget https://raw.githubusercontent.com/jgitver/jgitver-maven-plugin/master/src/doc/scripts/install.sh -O -)"# let's do some modifications/commits/tagsecho A > contentgit initgit 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-featureecho D > content && git add -u && git commit -m "added D data"git checkout masterecho E > content && git add -u && git commit -m "added E data"mvn validate

Then play around with it doing:

• mvn validate
• mvn install
• git checkout 1.0
• mvn validate
• git checkout cool-feature
• mvn 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 theContributing 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 usegrip.

• 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 sharingwith 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 Brouillardpublic key
• mvn -Poss,release -DskipTests clean deploy
• git push --follow-tags origin master

Since1.0.0, it is possible to totally skip the plugin execution by launching maven with the user propertyjgtiver.skip set totrue, 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 thelocal 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 theconfiguration 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 undertarget/local-repo and the IT tests will be executed fromtarget/it/XYZ.In this context, when executing tests, maven will try to activate extensions starting from thetarget/it/XYZ directory ; and it will find your extensions definition in the root directory of the project. This will lead in the activation ofjgitver-maven-plugin for all your IT projects AND for the poms inside the temporary local repository undertarget/local-repository.

To avoid such behavior, you need to telljgitver-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 (seeconfiguration):

<configuration>    <exclusions>        <exclusion>target/local-repo</exclusion>        <exclusion>target/it/**</exclusion>    </exclusions></configuration>

You can have a look at the configuration ofjgitver-maven-plugin itself.

jgitver-maven-plugin is delivered under theApache Licence, Version 2