maven-git-versioning-extension

by qoomon

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

148 Stars 40 Forks Last release: 9 months ago (v5.0.1) GNU General Public License v3.0 436 Commits 38 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Maven Git Versioning Extension

Maven Central Changelog

Build Workflow LGTM Grade

ℹ Also available as Gradle Plugin

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... * editing

pom.xml
* managing version by git and within files * Git merge conflicts

Example

Install

⚠️ minimal required maven version is

3.6.3

Add Extension

create or update

${basedir}/.mvn/extensions.xml
file
<extension>
    <groupid>me.qoomon</groupid>
    <artifactid>maven-git-versioning-extension</artifactid>
    <version>5.2.0</version>
</extension>

ℹ Consider CI/CD section when running this extension in a CI/CD environment

Configure Extension

You can configure the final version format for specific branches and tags separately.

Create

${basedir}/.mvn/maven-git-versioning-extension.xml
.

Example:

maven-git-versioning-extension.xml
    
        master
        ${version}
    
    
         .+)]]>
         ${feature}-SNAPSHOT
     
    
        [0-9].*)]]>
        ${tagVersion}
    
    
        ${commit.short}
    

  • optional

     global enable(
    true
    )/disable(
    false
    ) version update in original pom file.
  • optional

     global enable(
    true
    )/disable(
    false
    ) prefer tag rules over branch rules if both match.
  •  specific version format definition.
    
    
    •  An arbitrary regex to match branch names (has to be a full match pattern e.g. 
      feature/.+
      )
    •  An arbitrary string, see Version Format & Placeholders
      
    •  A property definition to update the value of a property
      
      
      •  An arbitrary regex to match property names
      •  The new value format of the property, see Version Format & Placeholders
        
      • optional
         An arbitrary regex to match and use capture group values of property value
    • optional
       Enable(
      true
      ) or disable(
      false
      ) version update in original pom fill (will override global
       value)
    • considered if...
      • HEAD attached to a branch
        git checkout 

      • Or branch name is provided by environment variable or command line parameter
  •  specific version format definition.
    
    
    •  An arbitrary regex to match tag names (has to be a full match pattern e.g. 
      v[0-9].*
      )
    •  An arbitrary string, see Version Format & Placeholders
      
    •  A property definition to update the value of a property
      
      
      •  An arbitrary regex to match property names
      •  The new value format of the property, see Version Format & Placeholders
        
      • optional
         An arbitrary regex to match and use capture group values of property value
    • optional
       Enable(
      true
      ) or disable(
      false
      ) version update in original pom fill (will override global
       value)
    • considered if...
      • HEAD is detached
        git checkout 

      • Or tag name is provided by environment variable or command line parameter
  •  specific version format definition.
    
    
    •  An arbitrary string, see Version Format & Placeholders
      
    •  A property definition to update the value of a property
      
      
      •  An arbitrary regex to match property names
      •  The new value format of the property, see Version Format & Placeholders
        
      • optional
         An arbitrary regex to match and use capture group values of property value
    • considered if...
      • HEAD is detached
        git checkout 
        and no matching version tag is pointing to HEAD

Version Format & Placeholders

/
characters within final version will be replaced by
-
**
  • ${ref}
    • current ref name (branch name, tag name or commit hash)
  • ${ref.slug}
    • like
      ${ref}
      with all
      /
      replaced by
      -
  • ${branch}
    (only available within branch configuration)
    • The branch name of
      HEAD
    • e.g. 'master', 'feature/next-big-thing', ...
  • ${tag}
    (only available within tag configuration)
    • The tag name that points at
      HEAD
      , if multiple tags point at
      HEAD
      latest version is selected
    • e.g. 'version/1.0.1', 'v1.2.3', ...
  • ${commit}
    • The
      HEAD
      commit hash
    • e.g. '0fc20459a8eceb2c4abb9bf0af45a6e8af17b94b'
  • ${commit.short}
    • The short
      HEAD
      commit hash (7 characters)
    • e.g. '0fc2045'
  • ${commit.timestamp}
    • The
      HEAD
      commit timestamp (epoch seconds)
    • e.g. '1560694278'
  • ${commit.timestamp.datetime}
    • The
      HEAD
      commit timestamp formatted as
      yyyyMMdd.HHmmss
    • e.g. '20190616.161442'
  • Pattern Groups
    • Contents of group in the regex pattern can be addressed by
      group name
      or
      group index
      e.g.
    • Named Group Example
      groovy
      pattern = 'feature/(?.+)'
      versionFormat = '${feature}-SNAPSHOT'    
      
    • Group Index Example
      groovy
      pattern = 'v([0-9].*)'
      versionFormat = '${1}'
      
  • ${version}
    • version
      set in
      pom.xml
    • e.g. '1.0.0-SNAPSHOT'
  • ${version.release}
    • version
      set in
      pom.xml
      without
      -SNAPSHOT
      postfix
    • e.g. '1.0.0'
  • ${property.name}
    • name of matching property
    • Only available within property format.
  • ${property.value}
    • value of matching property
    • Only available within property format.

Parameters & Environment Variables

  • Disable Extension

    • Environment Variables
      • export VERSIONING_DISABLE=true
    • Command Line Parameters
      • maven ... -Dversioning.disable=true
  • Provide branch or tag name

    • Environment Variables
      • export VERSIONING_GIT_BRANCH=$PROVIDED_BRANCH_NAME
      • export VERSIONING_GIT_TAG=$PROVIDED_TAG_NAME
    • Command Line Parameters
      • maven ... -Dgit.branch=$PROVIDED_BRANCH_NAME
      • maven ... -Dgit.tag=$PROVIDED_TAG_NAME

ℹ Especially useful for CI builds see Miscellaneous Hints

  • Update

    pom.xml
    • Environment Variables
      • export VERSIONING_UPDATE_POM=true
    • Command Line Parameters
      • maven ... -Dversioning.updatePom=true
  • Prefer Tags for Versioning instead of Branches

    • Environment Variables
      • export VERSIONING_PREFER_TAGS=true
    • Command Line Parameters
      • maven ... -Dversioning.preferTags=true

Provided Project Properties

  • git.commit
    e.g. '0fc20459a8eceb2c4abb9bf0af45a6e8af17b94b'
  • git.ref
    value of branch of tag name, always set
    • git.ref.slug
      like
      git.ref
      with all
      /
      replaced by
      -
    • git.branch
      e.g. 'feature/next-big-thing', only set for branch versioning
    • git.tag
      e.g. 'v1.2.3', only set for tag versioning
  • git.commit.timestamp
    e.g. '1560694278'
  • git.commit.timestamp.datetime
    e.g. '2019-11-16T14:37:10Z'
  • git.dirty
    repository dirty state indictor
    true
    or
    false

Miscellaneous Hints

Commandline To Print Project Version

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

Reproducible builds

The reproducible builds feature (https://maven.apache.org/guides/mini/guide-reproducible-builds.html) newly introduced in maven can be easily supported with this extension by using the latest commit timestamp as build timestamps.

xml
${git.commit.timestamp.datetime}

IntelliJ Setup

For a flawless experience you need to disable this extension during project import. Disable it by adding

-Dversioning.disable=true
to Maven Importer VM options (Preferences > Build, Execution, Deployment > Build Tools > Maven > Importing > VM options for importer).

CI/CD Setup

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, by using Parameters & Environment Variables. Below you'll find some setup example for common CI/CD systems.

GitHub Actions Setup

execute this snippet before running your

maven
command
shell
if [[ "$GITHUB_REF" = refs/heads/* ]]; then
    export VERSIONING_GIT_BRANCH=${GITHUB_REF#refs/heads/};
elif [[ "$GITHUB_REF" = refs/tags/* ]];
    export VERSIONING_GIT_TAG=${GITHUB_REF#refs/tags/};
fi

GitLab CI Setup

execute this snippet before running your

maven
command
shell
before_script:
  - if [ -n "$CI_COMMIT_TAG" ]; then
       export VERSIONING_GIT_TAG=$CI_COMMIT_TAG;
    else
       export VERSIONING_GIT_BRANCH=$CI_COMMIT_REF_NAME;
    fi

Jenkins Setup

execute this snippet before running your

maven
command
shell
if [[ "$GIT_BRANCH" = origin/tags/* ]]; then
    export VERSIONING_GIT_TAG=${GIT_BRANCH#origin/tags/};
else 
    export VERSIONING_GIT_BRANCH=${GIT_BRANCH#origin/};
fi

Build

  - mvn install
  # run integration tests after install, 
  # integration tests will run with LATEST version of extension installed
  - mvn failsafe:integration-test

Changelog

5.2.1

  • ⚠️ minimal required maven version is now
    3.6.3
  • remove workaround for maven
    3.6.2
    compatibility

5.2.0

  • BREAKING minimal required maven version set to
    3.6.3
  • new version format placeholder
    ${ref.slug}
    alike
    ${ref}
    with all
    /
    replaced by
    -
  • new property
    git.ref.slug
    alike
    git.ref
    with all
    /
    replaced by
    -

5.1.0

  • ⚠️ accidentally bump minimal required maven version to
    3.6.3
  • prevent maven from failing, if project is not part of a git repository. Instead a warning is logged.

5.0.2

  • fix incompatibility with maven version
    3.6.2

5.0.0

Features

  • simplify
     replacement configuration
    #### Fixes
  • add missing dependency vor maven version 3.3 #### Breaking Changes
  • simplify

     replacement configuration
    
    

    new config

    xml
    
        
            master
            ${version}
            
                revision
                ${branch-SNAPSHOT}
            
        
    
    
    old config
    xml
    
        
            master
            ${version}
            
                revision
                
                    ${branch-SNAPSHOT}
                
            
        
    
    

4.10.2

  • fix verbose logging when disabling extension by flag
  • restrict project versioning to root- and sub-projects

4.10.0

  • provide
    ${git.dirty}
    project property

4.8.0

  • set execution phase to INITIALIZE
    • Fix IntelliJ multi-modules project handling.

4.7.0

4.5.0

4.1.0

4.0.0

  • Major Refactoring, Simplification
  • Also available as Gradle Plugin
  • New Provided Project Properties
    • git.ref
      value of branch of tag name, always set

Breaking Changes

  • Restructured XML Config
  • Renamed Environment Variables
    • MAVEN_PROJECT_BRANCH
      ->
      VERSIONING_GIT_BRANCH
    • MAVEN_PROJECT_TAG
      ->
      VERSIONING_GIT_TAG
  • Renamed Maven Parameters
    • -Dproject.branch
      ->
      -Dgit.branch
    • -Dproject.tag
      ->
      -Dgit.tag
  • Removed Maven Parameters
    • -DgitVersioning
      - disable the extension by a parameter is no longer supported
  • Renamed Provided Project Properties
    • project.branch
      ->
      git.branch
    • project.tag
      ->
      git.tag
    • project.commit
      ->
      git.commit

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.