Gradle Git Versioning Plugin

ℹ Also available as Maven Extension

This plugin can virtually set project version and properties, based on current Git status.

ℹ No files will be modified, version and properties are modified in memory only.

• Get rid of...
  • editing build.gradle
  • managing project versions within files and Git tags
  • git merge conflicts

Usage

Add Plugin to Gradle Project

⚠️ Minimum required Java version 17, tested with Gradle 8.14 and newer

⚠️ You should apply git versioning (gitVersioning.apply{...}) directly after version declaration at root project only.

Groovy DSL build.gradle

plugins {
    id 'me.qoomon.git-versioning' version '6.4.4'
}

version = '0.0.0-SNAPSHOT'
gitVersioning.apply {
    // see configuration documentation below
}

Kotlin DSL build.gradle.kts

plugins {
    id("me.qoomon.git-versioning") version "6.4.4"
}

version = "0.0.0-SNAPSHOT"
gitVersioning.apply {
    // see configuration documentation below
}

Configure Plugin

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

You can configure the version and properties adjustments for specific branches and tags.

Groovy DSL Example: build.gradle

version = '0.0.0-SNAPSHOT'
gitVersioning.apply {
    refs {
        branch('.+') {
            version = '${ref}-SNAPSHOT'
        }
        tag('v(?<version>.*)') {
            version = '${ref.version}'
        }
    }

    // optional fallback configuration in case of no matching ref configuration
    rev {
        version = '${commit}'
    }
}

Kotlin DSL Example: build.gradle.kts

version = "0.0.0-SNAPSHOT"
gitVersioning.apply {
    refs {
        branch(".+") {
            version = "\${ref}-SNAPSHOT"
        }
        tag("v(?<version>.*)") {
            version = "\${ref.version}"
        }
    }

    // optional fallback configuration in case of no matching ref configuration
    rev {
        version = "\${commit}"
    }
}

Configuration Options

• disable global disable(true)/enable(false) extension, default is false.

  • Can be overridden by command option, see (Parameters & Environment Variables)[#parameters-&-environment-variables]

• describeTagPattern An arbitrary regex to match tag names for git describe command

  • has to be a full match pattern e.g. v(.+), default is .*

• describeTagFirstParent Enable(true) or disable(false) following only the first parent in a merge commit

  • default is true

• updateGradleProperties Enable(true)/disable(false) version and properties update in gradle.properties file, default is false

  • Can be overridden by command option, see (Parameters & Environment Variables)[#parameters-&-environment-variables]

• refs List of ref configurations, ordered by priority.

  • ℹ First matching configuration will be used.
    
    

  • considerTagsOnBranches By default, tags pointing at current commit will be ignored if HEAD is attached to a branch.

    • If this option is true tags will always be taken into account.
      
      

  • branch(pattern)/tag(pattern) specific ref patch definition.

    • pattern An arbitrary regex to match ref names

      • has to be a full match pattern e.g. main or feature/.+
        
        

    • describeTagPattern An arbitrary regex to match tag names for git describe command

      • has to be a full match pattern e.g. v.+)
      • will override global describeTagPattern value

    • describeTagFirstParent Enable(true) or disable(false) following only the first parent in a merge commit

      • default is true
        
        

    • version The new version format, see Format Placeholders

    • properties A property definitions to update the value of a property.

      • name The property name
      • value The new value format of the property, see Format Placeholders
        
        groovy

        properties = [
          "name" : "value",
        ]
        

        ⚠️ groovy.lang.MetaClass hides properties config field.
        If you need to call a method on `properties` config field, you need to use the alias field `properties_` e.g. `properties_.put("name", "value")`
        
        **kotlin** ```kotlin properties = mapOf( "name" to "value", ) ```
      
      

    • updateGradleProperties Enable(true) or disable(false) version and properties update in gradle.properties file

      • will override global updateGradleProperties value

• rev Rev configuration will be used if no ref configuration is matching current git situation.

  • same as branch(pattern)/tag(pattern) configuration, except pattern parameter.

Format Placeholders

ℹ ….slug placeholders means all / characters will be replaced by -.

ℹ Final version will be slugified automatically, so no need to use ${….slug} placeholders in version format.

ℹ define placeholder default value (placeholder is not defined) like this ${name:-DEFAULT_VALUE}
e.g ${env.BUILD_NUMBER:-0} or ${env.BUILD_NUMBER:-local}

ℹ define placeholder overwrite value (placeholder is defined) like this ${name:+OVERWRITE_VALUE}
e.g ${dirty:-SNAPSHOT} resolves to -SNAPSHOT instead of -DIRTY

Placeholders

• ${env.VARIABLE} Value of environment variable VARIABLE

• ${property.name} Value of commandline property -Pname=value
  
  

• ${version} version set in build.gradle e.g. '1.0.0-SNAPSHOT'

  • ${version.core} the core version component of ${version} e.g. '1.2.3'
  • ${version.major} the major version component of ${version} e.g. '1'
    • ${version.major.next} the ${version.major} increased by 1 e.g. '2'
  • ${version.minor} the minor version component of ${version} e.g. '2'
    • ${version.minor.next} the ${version.minor} increased by 1 e.g. '3'
  • ${version.patch} the patch version component of ${version} e.g. '3'
    • ${version.patch.next} the ${version.patch} increased by 1 e.g. '4'
  • ${version.label} the version label of ${version} e.g. 'SNAPSHOT'
    • ${version.label.prefixed} like ${version.label} with label separator e.g. '-SNAPSHOT'

• Project Version Pattern Groups

  • Content of regex groups in projectVersionPattern can be addressed like this:

  • ${version.GROUP_NAME}

  • ${version.GROUP_INDEX}

  • Named Group Example

    groovy

    projectVersionPattern = '^.+-(?<environment>.+)-SNAPSHOT$'
    branch('main') {
        version = '${version.environment}-SNAPSHOT'
    }
    

    kotlin

    projectVersionPattern = '^.+-(?<environment>.+)-SNAPSHOT\$'
    branch("main") {
        version = "\${version.environment}-SNAPSHOT"
    }
    

    
    

• ${ref} ${ref.slug} ref name (branch or tag name or commit hash)

• Ref Pattern Groups

  • Content of regex groups in branch/tag pattern can be addressed like this:

  • ${ref.GROUP_NAME} ${ref.GROUP_NAME.slug}

  • ${ref.GROUP_INDEX} ${ref.GROUP_INDEX.slug}

  • Named Group Example

    groovy

    branch('feature/(?<feature>.+)') {
        version = '${ref.feature}-SNAPSHOT'
    }
    

    kotlin

    branch("feature/(?<feature>.+)") {
        version = "\${ref.feature}-SNAPSHOT"
    }
    

    
    

• ${commit} commit hash '0fc20459a8eceb2c4abb9bf0af45a6e8af17b94b'

• ${commit.short} commit hash (7 characters) e.g. '0fc2045'

• ${commit.timestamp} commit timestamp (epoch seconds) e.g. '1560694278'

• ${commit.timestamp.year} commit year e.g. '2021'

• ${commit.timestamp.year.2digit} 2-digit commit year.g. '21'

• ${commit.timestamp.month} commit month of year e.g. '12'

• ${commit.timestamp.day} commit day of month e.g. '23'

• ${commit.timestamp.hour} commit hour of day (24h)e.g. '13'

• ${commit.timestamp.minute} commit minute of hour e.g. '59'

• ${commit.timestamp.second} commit second of minute e.g. '30'

• ${commit.timestamp.datetime} commit timestamp formatted as yyyyMMdd.HHmmsse.g. '20190616.161442'
  
  

• ${describe} Will resolve to git describe --tags --first-parent output

• ${describe.distance} The distance count to last matching tag

• ${describe.tag} The matching tag of git describe

  • ${describe.tag.version} the tag version determined by regex \d+\.\d+\.\d+
    • ${describe.tag.version.core} the core version component of ${describe.tag.version} e.g. '1.2.3'
    • ${describe.tag.version.major} the major version component of ${describe.tag.version} e.g. '1'
      • ${describe.tag.version.major.next} the ${describe.tag.version.major} increased by 1 e.g. '2'
    • ${describe.tag.version.minor} the minor version component of ${describe.tag.version} e.g. '2'
      • ${describe.tag.version.minor.next} the ${describe.tag.version.minor} increased by 1 e.g. '3'
    • ${describe.tag.version.patch} the patch version component of ${describe.tag.version} e.g. '3'
      • ${describe.tag.version.patch.next} the ${describe.tag.version.patch} increased by 1 e.g. '4'
      • ${describe.tag.version.patch.next.plus.describe.distance} the ${describe.tag.version.patch.next} increased by ${describe.distance} e.g. '3'
      • ${describe.tag.version.patch.plus.describe.distance} the ${describe.tag.version.patch} increased by ${describe.distance} e.g. '2'
    • ${describe.tag.version.label} the label version component of ${describe.tag.version} e.g. 'SNAPSHOT'
      • ${describe.tag.version.label.next} the ${describe.tag.version.label} converted to an integer and increased by 1 e.g. '6'
      • ${describe.tag.version.label.next.plus.describe.distance} the ${describe.tag.version.label.next} increased by ${describe.distance} e.g. '3'
      • ${describe.tag.version.label.plus.describe.distance} the ${describe.tag.version.label} increased by ${describe.distance} e.g. '2'

• Describe Tag Pattern Groups

  • Content of regex groups in describeTagPattern can be addressed like this:

  • ${describe.tag.GROUP_NAME} ${describe.tag.GROUP_NAME.slug}

  • ${describe.tag.GROUP_INDEX} ${describe.tag.GROUP_INDEX.slug}

  • Named Group Example

    groovy

    branch('main') {
        describeTagPattern = 'v(?<version>.*)'
        version = '${ref.feature}-SNAPSHOT'
    }
    

    kotlin

    branch("main") {
        describeTagPattern = "v(?<version>.*)"
        version = "\${describe.tag.version}-SNAPSHOT"
    }
    

    
    

• ${dirty} If repository has untracked files or uncommitted changes this placeholder will resolve to -DIRTY, otherwise it will resolve to an empty string.

  • ⚠️ Can lead to performance issue on very large projects (10,000+ files)

• ${dirty.snapshot} Like ${dirty}, but will resolve to -SNAPSHOT
  
  

• ${value} Original value of matching property (Only available within property format)

Parameters & Environment Variables

• Disable Extension

  • Environment Variables
  • export VERSIONING_DISABLE=true
  • Command Line Parameters
  • gradle … -Dversioning.disable

• Set branch or Add tag by environment variable

  • Environment Variables
  • export VERSIONING_GIT_REF=$PROVIDED_REF e.g. refs/heads/main, refs/tags/v1.0.0 or refs/pull/1000/head
  • export VERSIONING_GIT_BRANCH=$PROVIDED_BRANCH_NAME e.g. main or refs/heads/main
  • export VERSIONING_GIT_TAG=$PROVIDED_TAG_NAME e.g. v1.0.0 or refs/tags/v1.0.0
  • Command Line Parameters
  • gradle … -Dgit.ref=$PROVIDED_REF
  • gradle … -Dgit.branch=$PROVIDED_BRANCH_NAME
  • gradle … -Dgit.tag=$PROVIDED_TAG_NAME

  ℹ Especially useful for CI builds see Miscellaneous Hints

• Update gradle.properties file

  • Environment Variables
  • export VERSIONING_UPDATE_GRADLE_PROPERTIES=true
  • Command Line Parameters
  • gradle … -Dversioning.updateGradleProperties

Provided Project Properties

• git.commit e.g. '0fc20459a8eceb2c4abb9bf0af45a6e8af17b94b'

• git.commit.short e.g. '0fc2045'

• git.commit.timestamp e.g. '1560694278'

• git.commit.timestamp.datetime e.g. '2019-11-16T14:37:10Z'

• git.ref git.ref.slug HEAD ref name (branch or tag name or commit hash)

---

Configuration Cache

The plugin is compatible with the configuration cache. All git information is read through value sources, so a cached configuration is reused as long as the git information used by your version and property formats stays the same, and recalculated as soon as it changes (e.g. a new commit, a new tag or a dirty working tree if ${dirty} is used). Likewise, only the environment variables and properties referenced by ${env.*} and ${property.*} placeholders are configuration cache inputs.

• The plugin's log output (e.g. matching ref: ...) is only printed when the configuration is calculated, not when it is reused from the cache.
• With updateGradleProperties enabled, gradle.properties files are rewritten during configuration. As Gradle tracks these files, a rewrite causes one additional configuration cache miss.
• The plugin applies the version to all projects from the root project, so it is not compatible with isolated projects yet.

Gradle Tasks

• version
  • Print project version e.g. gradle :version -q

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.

Native Support

• GitHub Actions: if $GITHUB_ACTIONS == true, GITHUB_REF is considered
• GitLab CI: if $GITLAB_CI == true, CI_COMMIT_BRANCH, CI_COMMIT_TAG and CI_MERGE_REQUEST_SOURCE_BRANCH_NAME are considered
• Circle CI: if $CIRCLECI == true, CIRCLE_BRANCH and CIRCLE_TAG are considered
• Jenkins: if JENKINS_HOME is set, BRANCH_NAME and TAG_NAME are considered

Manual Setup

Set following environment variables before running your gradle command

export VERSIONING_GIT_REF=$PROVIDED_REF;

$PROVIDED_REF value examples: refs/heads/main, refs/tags/v1.0.0 or refs/pull/1000/head

or

export VERSIONING_GIT_BRANCH=$PROVIDED_BRANCH;
export VERSIONING_GIT_TAG=$PROVIDED_TAG;

$PROVIDED_BRANCH value examples: main, refs/heads/main or refs/pull/1000/head

$PROVIDED_TAG value examples: v1.0.0 or refs/tags/v1.0.0

---

Miscellaneous Hints

Commandline To Print Project Version

gradle :version -q

---

Build & Release

 # Publishes this plugin to local Maven
  ./gradlew build publishToMavenLocal
  # Publishes this plugin to Gradle Plugin portal.
  ./gradlew login && ./gradlew publishPlugins