This extension will virtually set project versions, based on current git branch or tag.
Clone or download
Bengt Brodersen
Bengt Brodersen refactor
Latest commit 3cd6ef8 Nov 9, 2018
Permalink
Failed to load latest commit information.
doc doc: fix image path Nov 8, 2017
src refactor Nov 9, 2018
.gitignore chroe: add .m2 to git ignore Nov 8, 2017
.travis.yml Create .travis.yml Dec 2, 2016
LICENSE Create LICENSE Sep 16, 2018
README.md Update README.md Sep 16, 2018
pom.xml refactor Nov 9, 2018

README.md

Maven Git Versioning Extension

Maven Central Build Status

This extension will virtually set project versions, based on current Git branch or Git tag.

The pom files will not be modified, versions are modified in memory only.

  • Get rid of...
    • managing version on two places (pom.xml <version> tag and Git version control)
    • pom.xml editing
    • Git merge conflicts

Example

Install

Add Extension

create or update ${basedir}/.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 http://maven.apache.org/xsd/core-extensions-1.0.0.xsd">

    <extension>
        <groupId>me.qoomon</groupId>
        <artifactId>maven-git-versioning-extension</artifactId>
        <version>LATEST</version>
    </extension>

</extensions>

ℹ Concidere CI/CD section when running this extention in a CI/CD environment

Configure Extension

Default Branch Version Format: ${branch}-SNAPSHOT

For Custom Configuration create ${project.basedir}/.mvn/maven-git-versioning-extension.xml.

  • <configuration>

    • <branches> Branch specific configurations.

      • <branch>

        • <pattern> An arbitrary regex to match branch names (has to be a full match pattern e.g. feature/.* )
        • <prefix> Remove prefix from ${branch} placeholder
        • <versionFormat> An arbitrary string, see Version Format & Placeholders

      only considered if...

      • HEAD attached to a branch git checkout <BRANCH>
      • Or branch name is provided by environment variable or maven parameter**
    • <tags> Tag specific configurations

      • <tag>

        • <pattern> An arbitrary regex to match tag names (has to be a full match pattern e.g. releases/.* )
        • <prefix> Remove prefix from ${tag} placeholder
        • <versionFormat> An arbitrary string, see Version Format & Placeholders

      only considered if...

      • HEAD is detached git checkout <TAG>
      • Or tag name is provided by environment variable or maven parameter**
    • <commit> Commit specific configurations

      only considered if...

      • HEAD is detached git checkout <COMMIT> and no matching version tag is pointing to HEAD
      • Or HEAD is detached and an empty tag is provided by environment variable or maven parameter
      • Or HEAD is attached to a branch and an empty branch is provided by environment variable or maven parameter**

Example Config maven-git-versioning-extension.xml

<configuration>
    <branches>
        <branch>
            <pattern>master</pattern>
            <versionFormat>${version.release}</versionFormat>
        </branch>
        <branch>
             <pattern>feature/.*</pattern>
             <prefix>feature/</prefix>
             <versionFormat>${branch}-SNAPSHOT</versionFormat>
         </branch>
        <branch>
             <pattern>release/.*</pattern>
             <prefix>release/</prefix>
             <versionFormat>${branch}-SNAPSHOT</versionFormat>
         </branch>
    </branches>
    <tags>
        <tag>
            <pattern>version/.*</pattern>
            <prefix>version/</prefix>
            <versionFormat>${tag}</versionFormat>
        </tag>
    </tags>
    <commit>
        <versionFormat>${commit}</versionFormat>
    </commit>
</configuration>

Version Format & Placeholders

'/' characters within version will be replaced by '-'

  • ${branch} (only available within branch configuration)

    • current branch name
    • e.g. 'master', 'feature-next-big-thing', ...
  • ${tag} (only available within tag configuration)

    • current tag name, if multiple tags point to current commit tag names are sorted by org.apache.maven.artifact.versioning.DefaultArtifactVersion and the last one is selected
    • e.g. 'version/1.0.1', 'version-1.0.0', ...
  • ${version}

    • pom file version
    • e.g. '1.2.3-SNAPSHOT'
  • ${version.release}

    • pom file version without '-SNAPSHOT'
    • e.g. '1.2.3'
  • ${commit}

    • current commit hash
    • e.g. '0fc20459a8eceb2c4abb9bf0af45a6e8af17b94b'
  • ${commit.short}

    • short current commit hash
    • e.g. '0fc2045'
  • ${PATTERN_GROUP_NAME or PATTERN_GROUP_INDEX}

    • Contents of group in the regex pattern can be addressed by group name or group index

      • Group Index
        <pattern>(feature)/(.*)]]></pattern>
        <versionFormat>${1}-${2}</versionFormat>
        
      • Named Group
        <pattern><![CDATA[(?<type>[^/]*)/(?<name>.*)]]></pattern>
        <versionformat>${type}-${name}</versionformat>
        

Parameters & Environment Variables

  • Provide branch or tag name

    • Environment Variables
      • export MAVEN_PROJECT_BRANCH=$CUSTOM_BRANCH_NAME
      • export MAVEN_PROJECT_TAG=$CUSTOM_TAG_NAME
    • Maven Parameters
      • mvn -Dproject.branch=$CUSTOM_BRANCH_NAME ...
      • mvn -Dproject.tag=$CUSTOM_TAG_NAME ...

    ℹ Especially useful for CI builds see Miscellaneous Hints

  • Disable Plugin

    • mvn -DgitVersioning=false ...

Provided Project Properties

  • project.branch
  • project.tag
  • project.commit

Miscellaneous Hints

Commandline To Print Project Version

mvn --non-recursive exec:exec -Dexec.executable='echo' -Dexec.args='${project.version}' -q

CI/CD

Most CI/CD systems do checkouts in a detached HEAD state so no branch information is available, however they provide environment variables with this information. You can provide those to the maven git versioning extension, by using Parameters & Environment Variables. Below you'll find some setup example for common CI/CD systems.

GitLab CI Setup

excute this snippet before running your maven command

before_script:
  - if [ -n "$CI_COMMIT_TAG" ]; then
       export MAVEN_PROJECT_TAG=$CI_COMMIT_TAG;
    else
       export MAVEN_PROJECT_BRANCH=$CI_COMMIT_REF_NAME;
    fi

Jenkins Setup

excute this snippet before running your maven command

if [[ "$GIT_BRANCH" = origin/tags/* ]]; then e
    export MAVEN_PROJECT_TAG=${GIT_BRANCH#origin/tags/};
else 
    export MAVEN_PROJECT_BRANCH=${GIT_BRANCH#origin/};
fi

or for maven plugin (without tag support)

maven <Goal> -Dproject.branch=${GIT_BRANCH#origin/}