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
⚠️ 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 '5.2.0'
}
version ='0.0.0-SNAPSHOT'
gitVersioning.apply {
// see configuration documentation below
}
Kotlin DSL build.gradle.kts
plugins {
id("me.qoomon.git-versioning") version "5.2.0"
}
// ...
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 .*
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
⚠️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.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'
${version.release} like ${version} without version labels like -SNAPSHOT e.g. '1.2.3'
${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"
}
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
Provide branch or tag name
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
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.refgit.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 and CI_COMMIT_TAG 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
$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
./gradlew build
# Publishes this plugin to local Maven
./gradlew publishToMavenLocal
# Publishes this plugin to Gradle Plugin portal.
./gradlew login && ./gradlew publishPlugins
请发表评论