https://github.com/palantir/gradle-git-version
a Gradle plugin that uses `git describe` to produce a version string.
https://github.com/palantir/gradle-git-version
octo-correct-managed
Last synced: 6 months ago
JSON representation
a Gradle plugin that uses `git describe` to produce a version string.
- Host: GitHub
- URL: https://github.com/palantir/gradle-git-version
- Owner: palantir
- License: apache-2.0
- Created: 2015-09-17T21:21:50.000Z (over 10 years ago)
- Default Branch: develop
- Last Pushed: 2025-05-14T20:24:19.000Z (11 months ago)
- Last Synced: 2025-05-14T21:29:24.079Z (11 months ago)
- Topics: octo-correct-managed
- Language: Groovy
- Homepage:
- Size: 1.64 MB
- Stars: 400
- Watchers: 271
- Forks: 76
- Open Issues: 55
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog/0.12.1/pr-152.v2.yml
- License: LICENSE
Awesome Lists containing this project
- awesome - palantir/gradle-git-version - a Gradle plugin that uses `git describe` to produce a version string. (<a name="Groovy"></a>Groovy)
README
Git-Version Gradle Plugin
=========================
[](https://circleci.com/gh/palantir/gradle-git-version)
[](https://plugins.gradle.org/plugin/com.palantir.git-version)
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, 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**
```groovy
plugins {
id 'com.palantir.git-version' version ''
}
```
**Kotlin**
```kotlin
plugins {
id("com.palantir.git-version") version ""
}
```
Set the version of a project by calling:
**Groovy**
```groovy
version gitVersion()
```
**Kotlin**
```kotlin
val gitVersion: groovy.lang.Closure by extra
version = gitVersion()
```
You can get an object containing more detailed information by calling:
**Groovy**
```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**
```kotlin
val versionDetails: groovy.lang.Closure 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 my-product@2.15.0:
**Groovy**
```groovy
gitVersion(prefix:'my-product@') // -> 2.15.0
```
**Kotlin**
```kotlin
val gitVersion: groovy.lang.Closure 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](https://docs.gradle.org/current/userguide/configuration_cache.html).
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`](https://docs.gradle.org/current/javadoc/org/gradle/process/ExecOutput.html#getResult()). 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...
```bash
./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](http://www.apache.org/licenses/LICENSE-2.0).