Repository files navigation

As of gradle-git-version 4.0, minimum supported JDK version is JDK 17 - in preparation for Gradle 9.0.

When applied, Git-Version adds two methods to the target project.

The first, calledgitVersion(), mimicsgit describe --tags --always --first-parent to determine a version string.It behaves exactly asgit describe --tags --always --first-parent method behaves, except that when the repository isin a dirty state, appends.dirty to the version string.

The second, calledversionDetails(), returns an object containing the specific details of the version string:the tag name, the commit count since the tag, the current commit hash of HEAD, and an optional branch name of HEAD.

Apply the plugin using standard Gradle convention:

Groovy

plugins {    id'com.palantir.git-version' version'<current version>'}

Kotlin

plugins {    id("com.palantir.git-version") version"<current version>"}

Set the version of a project by calling:

Groovy

version gitVersion()

Kotlin

val gitVersion: groovy.lang.Closure<String> by extraversion= gitVersion()

You can get an object containing more detailed information by calling:

Groovy

def details= versionDetails()details.lastTagdetails.commitDistancedetails.gitHashdetails.gitHashFull// full 40-character Git commit hashdetails.branchName// is null if the repository in detached HEAD modedetails.isCleanTag

Kotlin

val versionDetails: groovy.lang.Closure<com.palantir.gradle.gitversion.VersionDetails> by extraval details= versionDetails()details.lastTagdetails.commitDistancedetails.gitHashdetails.gitHashFull// full 40-character Git commit hashdetails.branchName// is null if the repository in detached HEAD modedetails.isCleanTag

You can optionally search a subset of tags withprefix. Example when the tag is my-product@2.15.0:

Groovy

gitVersion(prefix:'my-product@')// -> 2.15.0

Kotlin

val gitVersion: groovy.lang.Closure<String> by extragitVersion(mapOf("prefix" to"my-product@"))// -> 2.15.0

Valid prefixes are defined by the regex[/@]?([A-Za-z0-9]+[/@-])+.

/Abc/Abc@foo-bar@foo/bar-v2@

This plugin adds aprintVersion task, which will echo the project's configured versionto standard-out.

External process calls togit in this plugin are compatible with Gradle'sConfiguration Cache.

Since we're using Configuration Cache compatible APIs, we leverage Gradle's ability to reuse outputs ofgit commands upon successive invocations.

VersionDetails caches calls togit with Gradle'sProvider<ExecOutput>. External calls can be expensive, especially if called repeatedly across multiple projects. Caching prevents running the samegit command more than once in a single build.

However, changes to the state of your repo between gradle builds i.e. two runs of gradle...

./gradlew checkgit commit -m"new commit"./gradlew check

...are not affected by this, as the cache is scoped to individualVersionDetails instances.

This plugin is made available under theApache 2.0 License.