{"id":21870196,"url":"https://github.com/qoomon/gradle-git-versioning-plugin","last_synced_at":"2025-04-05T21:07:01.609Z","repository":{"id":37708326,"uuid":"169088001","full_name":"qoomon/gradle-git-versioning-plugin","owner":"qoomon","description":"This extension will set project version, based on current Git branch or tag.","archived":false,"fork":false,"pushed_at":"2024-11-20T15:38:14.000Z","size":691,"stargazers_count":101,"open_issues_count":16,"forks_count":11,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T20:04:06.461Z","etag":null,"topics":["branch","generated","git","git-describe","gradle","gradle-plugin","maven","maven-extension","maven-plugin","repository","tag","versioning"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qoomon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-04T14:09:33.000Z","updated_at":"2025-03-25T14:00:07.000Z","dependencies_parsed_at":"2023-11-16T10:24:58.147Z","dependency_job_id":"463ef00f-fe24-4a51-803f-cc81c6430351","html_url":"https://github.com/qoomon/gradle-git-versioning-plugin","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qoomon%2Fgradle-git-versioning-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qoomon%2Fgradle-git-versioning-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qoomon%2Fgradle-git-versioning-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qoomon%2Fgradle-git-versioning-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qoomon","download_url":"https://codeload.github.com/qoomon/gradle-git-versioning-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247399874,"owners_count":20932876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["branch","generated","git","git-describe","gradle","gradle-plugin","maven","maven-extension","maven-plugin","repository","tag","versioning"],"created_at":"2024-11-28T06:10:36.445Z","updated_at":"2025-04-05T21:07:01.587Z","avatar_url":"https://github.com/qoomon.png","language":"Java","readme":"# Gradle Git Versioning Plugin [![starline](https://starlines.qoo.monster/assets/qoomon/gradle-git-versioning-plugin)](https://github.com/qoomon/starlines)\n\n[![Gradle Plugin Portal](https://img.shields.io/maven-metadata/v/https/plugins.gradle.org/m2/me/qoomon/gradle-git-versioning-plugin/maven-metadata.xml.svg?colorB=007ec6\u0026label=gradle-plugin)](https://plugins.gradle.org/plugin/me.qoomon.git-versioning)\n[![Changelog](https://badgen.net/badge/changelog/%E2%98%85/blue)](CHANGELOG.md)\n[![Build Workflow](https://github.com/qoomon/gradle-git-versioning-plugin/workflows/Build/badge.svg)](https://github.com/qoomon/gradle-git-versioning-plugin/actions)\n[![LGTM Grade](https://img.shields.io/lgtm/grade/java/github/qoomon/gradle-git-versioning-plugin)](https://lgtm.com/projects/g/qoomon/gradle-git-versioning-plugin)\n\n\n**ℹ Also available as [Maven Extension](https://github.com/qoomon/maven-git-versioning-extension)**\n\n![Example](doc/GradleGitVersioningPlugin.png)\n\nThis plugin can virtually set project version and properties, based on current **Git status**.\n\nℹ **No files will be modified, version and properties are modified in memory only.**\n\n* Get rid of...\n    * editing `build.gradle`\n    * managing project versions within files and Git tags\n    * git merge conflicts\n\n## Usage\n\n### Add Plugin to Gradle Project\n⚠️ Minimum required Java version `11` \n\n⚠️ You should apply git versioning (`gitVersioning.apply{...}`) directly after `version` declaration at root project only.\n\n#### Groovy DSL `build.gradle`\n\n```groovy\nplugins {\n    id 'me.qoomon.git-versioning' version '6.4.4'\n}\n\nversion = '0.0.0-SNAPSHOT'\ngitVersioning.apply {\n    // see configuration documentation below\n}\n```\n\n#### Kotlin DSL `build.gradle.kts`\n\n```kotlin\nplugins {\n    id(\"me.qoomon.git-versioning\") version \"6.4.4\"\n}\n\nversion = \"0.0.0-SNAPSHOT\"\ngitVersioning.apply {\n    // see configuration documentation below\n}\n```\n\n## Configure Plugin\n\nℹ Consider [CI/CD](#cicd-setup) section when running this plugin in a CI/CD environment\n\nYou can configure the version and properties adjustments for specific branches and tags.\n\n**Groovy DSL Example:** `build.gradle`\n\n```groovy\nversion = '0.0.0-SNAPSHOT'\ngitVersioning.apply {\n    refs {\n        branch('.+') {\n            version = '${ref}-SNAPSHOT'\n        }\n        tag('v(?\u003cversion\u003e.*)') {\n            version = '${ref.version}'\n        }\n    }\n\n    // optional fallback configuration in case of no matching ref configuration\n    rev {\n        version = '${commit}'\n    }\n}\n```\n\n**Kotlin DSL Example:** `build.gradle.kts`\n\n```kotlin\nversion = \"0.0.0-SNAPSHOT\"\ngitVersioning.apply {\n    refs {\n        branch(\".+\") {\n            version = \"\\${ref}-SNAPSHOT\"\n        }\n        tag(\"v(?\u003cversion\u003e.*)\") {\n            version = \"\\${ref.version}\"\n        }\n    }\n\n    // optional fallback configuration in case of no matching ref configuration\n    rev {\n        version = \"\\${commit}\"\n    }\n}\n```\n\n### Configuration Options\n\n- `disable` global disable(`true`)/enable(`false`) extension, default is `false`.\n    - Can be overridden by command option, see (Parameters \u0026 Environment Variables)[#parameters-\u0026-environment-variables]\n\n- `describeTagPattern` An arbitrary regex to match tag names for git describe command\n  - has to be a **full match pattern** e.g. `v(.+)`, default is `.*`\n- `describeTagFirstParent` Enable(`true`) or disable(`false`) following only the first parent in a merge commit\n  - default is `true`\n  \n- `updateGradleProperties` Enable(`true`)/disable(`false`) version and properties update in `gradle.properties` file, default is `false`\n    - Can be overridden by command option, see (Parameters \u0026 Environment Variables)[#parameters-\u0026-environment-variables]\n\n- `refs` List of ref configurations, ordered by priority.\n    - ℹ First matching configuration will be used.\n      \u003cbr\u003e\u003cbr\u003e\n\n    - `considerTagsOnBranches` By default, tags pointing at current commit will be ignored if HEAD is attached to a branch.\n      - If this option is `true` tags will always be taken into account.\n        \u003cbr\u003e\u003cbr\u003e\n\n    - `branch(pattern)`/`tag(pattern)` specific ref patch definition.\n      - `pattern` An arbitrary regex to match ref names\n        - has to be a **full match pattern** e.g. `main` or `feature/.+`\n          \u003cbr\u003e\u003cbr\u003e\n\n      - `describeTagPattern` An arbitrary regex to match tag names for git describe command\n        - has to be a **full match pattern** e.g. `v.+`)\n        - will override global `describeTagPattern` value\n      - `describeTagFirstParent` Enable(`true`) or disable(`false`) following only the first parent in a merge commit\n        - default is `true`\n          \u003cbr\u003e\u003cbr\u003e\n\n      - `version` The new version format, see [Format Placeholders](#format-placeholders)\n      - `properties` A property definitions to update the value of a property. \n        - `name` The property name \n        - `value` The new value format of the property, see [Format Placeholders](#format-placeholders)\n          \u003cbr\u003e\u003cbr\u003e\n          **groovy**\n          ```groovy\n          properties = [\n            \"name\" : \"value\",\n          ]\n          ```\n          ⚠️  `groovy.lang.MetaClass` hides `properties` config field. \n          \u003cbr\u003e \n          If you need to call a method on `properties` config field, you need to use the alias field `properties_` e.g.\n          `properties_.put(\"name\", \"value\")`\n          \u003cbr\u003e\u003cbr\u003e\n          **kotlin**\n          ```kotlin\n          properties = mapOf(\n            \"name\" to \"value\",\n          )            \n          ```\n        \u003cbr\u003e\n\n      - `updateGradleProperties` Enable(`true`) or disable(`false`) version and properties update in `gradle.properties` file\n        - will override global `updateGradleProperties` value\n\n- `rev` Rev configuration will be used if no ref configuration is matching current git situation.\n    - same as `branch(pattern)`/`tag(pattern)` configuration, except `pattern` parameter.\n\n### Format Placeholders\n\nℹ `….slug` placeholders means all `/` characters will be replaced by `-`.\n\nℹ Final `version` will be slugified automatically, so no need to use `${….slug}` placeholders in `version` format.\n\nℹ define placeholder default value (placeholder is not defined) like this `${name:-DEFAULT_VALUE}`\u003cbr\u003e\ne.g `${env.BUILD_NUMBER:-0}` or `${env.BUILD_NUMBER:-local}`\n\nℹ define placeholder overwrite value (placeholder is defined) like this `${name:+OVERWRITE_VALUE}`\u003cbr\u003e\ne.g `${dirty:-SNAPSHOT}` resolves to `-SNAPSHOT` instead of `-DIRTY`\n\n###### Placeholders\n\n- `${env.VARIABLE}` Value of environment variable `VARIABLE`\n- `${property.name}` Value of commandline property `-Pname=value`\n  \u003cbr\u003e\u003cbr\u003e\n\n- `${version}` `version` set in `build.gradle` e.g. '1.0.0-SNAPSHOT'\n  - `${version.core}` the core version component of `${version}` e.g. '1.2.3'\n  - `${version.major}` the major version component of `${version}` e.g. '1'\n    - `${version.major.next}` the `${version.major}` increased by 1 e.g. '2'\n  - `${version.minor}` the minor version component of `${version}` e.g. '2'\n    - `${version.minor.next}` the `${version.minor}` increased by 1 e.g. '3'\n  - `${version.patch}` the patch version component of `${version}` e.g. '3'\n    - `${version.patch.next}` the `${version.patch}` increased by 1 e.g. '4'\n  - `${version.label}` the version label of `${version}` e.g. 'SNAPSHOT'\n    - `${version.label.prefixed}` like `${version.label}` with label separator e.g. '-SNAPSHOT'\n- Project Version Pattern Groups\n  - Content of regex groups in `projectVersionPattern` can be addressed like this:\n  - `${version.GROUP_NAME}`\n  - `${version.GROUP_INDEX}`\n  - Named Group Example\n\n    **groovy**\n      ```groovy\n      projectVersionPattern = '^.+-(?\u003cenvironment\u003e.+)-SNAPSHOT$'\n      branch('main') {\n          version = '${version.environment}-SNAPSHOT'\n      }\n      ```\n    **kotlin**\n      ```kotlin\n      projectVersionPattern = '^.+-(?\u003cenvironment\u003e.+)-SNAPSHOT\\$'\n      branch(\"main\") {\n          version = \"\\${version.environment}-SNAPSHOT\"\n      }\n      ```\n      \u003cbr\u003e \n\n- `${ref}` `${ref.slug}` ref name (branch or tag name or commit hash)\n- Ref Pattern Groups\n    - Content of regex groups in branch/tag `pattern` can be addressed like this:\n    - `${ref.GROUP_NAME}` `${ref.GROUP_NAME.slug}`\n    - `${ref.GROUP_INDEX}` `${ref.GROUP_INDEX.slug}`\n    - Named Group Example\n      \n        **groovy**\n        ```groovy\n        branch('feature/(?\u003cfeature\u003e.+)') {\n            version = '${ref.feature}-SNAPSHOT'\n        }\n        ```\n        **kotlin**\n        ```kotlin\n        branch(\"feature/(?\u003cfeature\u003e.+)\") {\n            version = \"\\${ref.feature}-SNAPSHOT\"\n        }\n        ```\n        \u003cbr\u003e\n\n- `${commit}` commit hash '0fc20459a8eceb2c4abb9bf0af45a6e8af17b94b'\n- `${commit.short}` commit hash (7 characters) e.g. '0fc2045'\n- `${commit.timestamp}` commit timestamp (epoch seconds) e.g. '1560694278'\n- `${commit.timestamp.year}` commit year e.g. '2021'\n- `${commit.timestamp.year.2digit}` 2-digit commit year.g. '21'\n- `${commit.timestamp.month}` commit month of year e.g. '12'\n- `${commit.timestamp.day}` commit day of month e.g. '23'\n- `${commit.timestamp.hour}` commit hour of day (24h)e.g. '13'\n- `${commit.timestamp.minute}` commit minute of hour e.g. '59'\n- `${commit.timestamp.second}` commit second of minute e.g. '30'\n- `${commit.timestamp.datetime}` commit timestamp formatted as `yyyyMMdd.HHmmss`e.g. '20190616.161442'\n  \u003cbr\u003e\u003cbr\u003e\n\n- `${describe}` Will resolve to `git describe --tags --first-parent` output\n- `${describe.distance}` The distance count to last matching tag\n- `${describe.tag}` The matching tag of `git describe`\n  - `${describe.tag.version}` the tag version determined by regex `\\d+\\.\\d+\\.\\d+`\n    - `${describe.tag.version.core}` the core version component of `${describe.tag.version}` e.g. '1.2.3'\n    - `${describe.tag.version.major}` the major version component of `${describe.tag.version}` e.g. '1'\n      - `${describe.tag.version.major.next}` the `${describe.tag.version.major}` increased by 1 e.g. '2'\n    - `${describe.tag.version.minor}` the minor version component of `${describe.tag.version}` e.g. '2'\n      - `${describe.tag.version.minor.next}` the `${describe.tag.version.minor}` increased by 1 e.g. '3'\n    - `${describe.tag.version.patch}` the patch version component of `${describe.tag.version}` e.g. '3'\n      - `${describe.tag.version.patch.next}` the `${describe.tag.version.patch}` increased by 1 e.g. '4'\n      - `${describe.tag.version.patch.next.plus.describe.distance}` the `${describe.tag.version.patch.next}` increased by `${describe.distance}` e.g. '3'\n      - `${describe.tag.version.patch.plus.describe.distance}` the `${describe.tag.version.patch}` increased by `${describe.distance}` e.g. '2'\n    - `${describe.tag.version.label}` the label version component of `${describe.tag.version}` e.g. 'SNAPSHOT'\n      - `${describe.tag.version.label.next}` the `${describe.tag.version.label}` converted to an integer and increased by 1 e.g. '6'\n      - `${describe.tag.version.label.next.plus.describe.distance}` the `${describe.tag.version.label.next}` increased by `${describe.distance}` e.g. '3'\n      - `${describe.tag.version.label.plus.describe.distance}` the `${describe.tag.version.label}` increased by `${describe.distance}` e.g. '2'\n- Describe Tag Pattern Groups\n  - Content of regex groups in `describeTagPattern` can be addressed like this:\n  - `${describe.tag.GROUP_NAME}` `${describe.tag.GROUP_NAME.slug}`\n  - `${describe.tag.GROUP_INDEX}` `${describe.tag.GROUP_INDEX.slug}`\n  - Named Group Example\n\n      **groovy**\n      ```groovy\n      branch('main') {\n          describeTagPattern = 'v(?\u003cversion\u003e.*)'\n          version = '${ref.feature}-SNAPSHOT'\n      }\n      ```\n      **kotlin**\n      ```kotlin\n      branch(\"main\") {\n          describeTagPattern = \"v(?\u003cversion\u003e.*)\"\n          version = \"\\${describe.tag.version}-SNAPSHOT\"\n      }\n      ```\n      \u003cbr\u003e \n\n- `${dirty}` If repository has untracked files or uncommitted changes this placeholder will resolve to `-DIRTY`, otherwise it will resolve to an empty string.\n    - ⚠️ Can lead to performance issue on very large projects (10,000+ files)\n- `${dirty.snapshot}` Like `${dirty}`, but will resolve to `-SNAPSHOT`\n  \u003cbr\u003e\u003cbr\u003e\n\n- `${value}` Original value of matching property (Only available within property format)\n\n\n### Parameters \u0026 Environment Variables\n\n- Disable Extension\n    - **Environment Variables**\n     - `export VERSIONING_DISABLE=true`\n    - **Command Line Parameters**\n     - `gradle … -Dversioning.disable`\n\n- Set **branch** or Add **tag** by environment variable\n    - **Environment Variables**\n     - `export VERSIONING_GIT_REF=$PROVIDED_REF` e.g. `refs/heads/main`, `refs/tags/v1.0.0` or `refs/pull/1000/head`\n     - `export VERSIONING_GIT_BRANCH=$PROVIDED_BRANCH_NAME` e.g. `main` or `refs/heads/main`\n     - `export VERSIONING_GIT_TAG=$PROVIDED_TAG_NAME` e.g. `v1.0.0` or `refs/tags/v1.0.0`\n    - **Command Line Parameters**\n     - `gradle … -Dgit.ref=$PROVIDED_REF`\n     - `gradle … -Dgit.branch=$PROVIDED_BRANCH_NAME`\n     - `gradle … -Dgit.tag=$PROVIDED_TAG_NAME`\n\n  ℹ Especially useful for **CI builds** see [Miscellaneous Hints](#miscellaneous-hints)\n\n- Update `gradle.properties` file\n    - **Environment Variables**\n     - `export VERSIONING_UPDATE_GRADLE_PROPERTIES=true`\n    - **Command Line Parameters**\n     - `gradle … -Dversioning.updateGradleProperties`\n\n## Provided Project Properties\n\n- `git.commit` e.g. '0fc20459a8eceb2c4abb9bf0af45a6e8af17b94b'\n- `git.commit.short` e.g. '0fc2045'\n- `git.commit.timestamp` e.g. '1560694278'\n- `git.commit.timestamp.datetime` e.g. '2019-11-16T14:37:10Z'\n\n- `git.ref` `git.ref.slug` HEAD ref name (branch or tag name or commit hash)\n\n---\n\n## Gradle Tasks\n\n* `version`\n    * Print project version e.g. `gradle :version -q`\n\n## CI/CD Setup\n\nMost CI/CD systems do checkouts in a detached HEAD state so no branch information is available, however they provide environment variables with this information. \nYou can provide those, by using [Parameters \u0026 Environment Variables](#parameters--environment-variables).\n\n### Native Support\n\n* GitHub Actions: if `$GITHUB_ACTIONS == true`, `GITHUB_REF` is considered\n* GitLab CI: if `$GITLAB_CI == true`, `CI_COMMIT_BRANCH`, `CI_COMMIT_TAG` and `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` are considered\n* Circle CI: if `$CIRCLECI == true`, `CIRCLE_BRANCH` and `CIRCLE_TAG` are considered\n* Jenkins: if `JENKINS_HOME` is set, `BRANCH_NAME` and `TAG_NAME` are considered\n\n### Manual Setup\n\nSet following environment variables before running your `gradle` command\n\n```shell\nexport VERSIONING_GIT_REF=$PROVIDED_REF;\n```\n\n`$PROVIDED_REF` value examples: `refs/heads/main`, `refs/tags/v1.0.0` or `refs/pull/1000/head`\n\nor\n\n```shell\nexport VERSIONING_GIT_BRANCH=$PROVIDED_BRANCH;\nexport VERSIONING_GIT_TAG=$PROVIDED_TAG;\n```\n\n`$PROVIDED_BRANCH` value examples: `main`, `refs/heads/main` or `refs/pull/1000/head`\n\n`$PROVIDED_TAG` value examples: `v1.0.0` or `refs/tags/v1.0.0`\n\n---\n\n## Miscellaneous Hints\n\n### Commandline To Print Project Version\n\n`gradle :version -q`\n\n---\n\n## Build \u0026 Release\n\n```shell\n # Publishes this plugin to local Maven\n  ./gradlew build publishToMavenLocal\n  # Publishes this plugin to Gradle Plugin portal.\n  ./gradlew login \u0026\u0026 ./gradlew publishPlugins\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqoomon%2Fgradle-git-versioning-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqoomon%2Fgradle-git-versioning-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqoomon%2Fgradle-git-versioning-plugin/lists"}