/gradle-git-versioning-plugin

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

Primary LanguageJavaGNU General Public License v3.0GPL-3.0

Gradle Git Versioning Plugin Sparkline

Gradle Plugin Portal Changelog Build Workflow LGTM Grade

ℹ Also available as Maven Extension

Example

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