Git-Version Gradle Plugin

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

The first, called gitVersion(), mimics git describe --tags --always --first-parent to determine a version string. It behaves exactly as git describe --tags --always --first-parent method behaves, except that when the repository is in a dirty state, appends .dirty to the version string.

The second, called versionDetails(), 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.

Usage

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 extra
version = gitVersion()

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

Groovy

def details = versionDetails()
details.lastTag
details.commitDistance
details.gitHash
details.gitHashFull // full 40-character Git commit hash
details.branchName // is null if the repository in detached HEAD mode
details.isCleanTag

Kotlin

val versionDetails: groovy.lang.Closure<com.palantir.gradle.gitversion.VersionDetails> by extra
val details = versionDetails()
details.lastTag
details.commitDistance
details.gitHash
details.gitHashFull // full 40-character Git commit hash
details.branchName // is null if the repository in detached HEAD mode
details.isCleanTag

You can optionally search a subset of tags with prefix. Example when the tag is [email protected]:

Groovy

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

Kotlin

val gitVersion: groovy.lang.Closure<String> by extra
gitVersion(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@

Tasks

This plugin adds a printVersion task, which will echo the project's configured version to standard-out.

☑️ Configuration cache

External process calls to git in this plugin are compatible with Gradle's Configuration Cache.

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

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

Warning

If the state of the git repo changes within a single gradle session (e.g. a task in the build does git commit), VersionDetails might reflect the outdated state of your repo.

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

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

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

License

This plugin is made available under the Apache 2.0 License.