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 11

⚠️ 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
      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)

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Gradle Git Versioning Plugin

Usage

Add Plugin to Gradle Project

Groovy DSL `build.gradle`

Kotlin DSL `build.gradle.kts`

Configure Plugin

Configuration Options

Format Placeholders

Placeholders

Parameters & Environment Variables

Provided Project Properties

Gradle Tasks

CI/CD Setup

Native Support

Manual Setup

Miscellaneous Hints

Commandline To Print Project Version

Build & Release

Files

README.md

Latest commit

History

README.md

File metadata and controls

Gradle Git Versioning Plugin

Usage

Add Plugin to Gradle Project

Groovy DSL build.gradle

Kotlin DSL build.gradle.kts

Configure Plugin

Configuration Options

Format Placeholders

Placeholders

Parameters & Environment Variables

Provided Project Properties

Gradle Tasks

CI/CD Setup

Native Support

Manual Setup

Miscellaneous Hints

Commandline To Print Project Version

Build & Release

Groovy DSL `build.gradle`

Kotlin DSL `build.gradle.kts`