{"id":46269827,"url":"https://github.com/jmongard/git.semversioning.gradle","last_synced_at":"2026-03-04T03:01:29.220Z","repository":{"id":55592493,"uuid":"248187973","full_name":"jmongard/Git.SemVersioning.Gradle","owner":"jmongard","description":"Gradle plugin for automatically versioning a project using semantic versioning and conventional commits with change log support based on git commit messages.","archived":false,"fork":false,"pushed_at":"2025-11-22T23:00:21.000Z","size":629,"stargazers_count":51,"open_issues_count":5,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-11-22T23:23:40.120Z","etag":null,"topics":["change-log","changelog","conventional-commits","git","gradle","semantic","semver","versioning"],"latest_commit_sha":null,"homepage":"https://plugins.gradle.org/plugin/com.github.jmongard.git-semver-plugin","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jmongard.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-03-18T09:27:06.000Z","updated_at":"2025-11-10T09:29:51.000Z","dependencies_parsed_at":"2024-02-15T12:25:52.746Z","dependency_job_id":"2b7bc659-fbe0-4625-9c89-0f8f8ffdcae5","html_url":"https://github.com/jmongard/Git.SemVersioning.Gradle","commit_stats":null,"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"purl":"pkg:github/jmongard/Git.SemVersioning.Gradle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmongard%2FGit.SemVersioning.Gradle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmongard%2FGit.SemVersioning.Gradle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmongard%2FGit.SemVersioning.Gradle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmongard%2FGit.SemVersioning.Gradle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmongard","download_url":"https://codeload.github.com/jmongard/Git.SemVersioning.Gradle/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmongard%2FGit.SemVersioning.Gradle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30070479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T01:03:42.280Z","status":"online","status_checked_at":"2026-03-04T02:00:07.464Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["change-log","changelog","conventional-commits","git","gradle","semantic","semver","versioning"],"created_at":"2026-03-04T03:01:28.604Z","updated_at":"2026-03-04T03:01:29.207Z","avatar_url":"https://github.com/jmongard.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Git Semantic Versioning Plugin for Gradle\n[![Gradle Build](https://github.com/jmongard/Git.SemVersioning.Gradle/workflows/Gradle%20Build/badge.svg)](https://github.com/jmongard/Git.SemVersioning.Gradle/actions/workflows/gradle-push.yml)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=jmongard_Git.SemVersioning.Gradle\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=jmongard_Git.SemVersioning.Gradle)\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=jmongard_Git.SemVersioning.Gradle\u0026metric=ncloc)](https://sonarcloud.io/summary/new_code?id=jmongard_Git.SemVersioning.Gradle)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=jmongard_Git.SemVersioning.Gradle\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=jmongard_Git.SemVersioning.Gradle)\n[![GitHub tag (with filter)](https://img.shields.io/github/v/tag/jmongard/Git.SemVersioning.Gradle?logo=gradle\u0026label=Release)](https://plugins.gradle.org/plugin/com.github.jmongard.git-semver-plugin)\n\nA Gradle plugin that automatically versions your project using semantic versioning and conventional commits. It analyzes Git commit messages to determine version increments and generates change logs based on your commit history.\n\n\n## Usage\n\nApply the plugin using standard Gradle convention and set the version of the project: \n\n```groovy\nplugins {\n    id 'com.github.jmongard.git-semver-plugin' version '\u003ccurrent version\u003e'\n}\n\n//semver { ... } // Optionally add configuration for the plugin before getting the version\n\n//Set the version for the current project:\nversion = semver.version\n\n//Or in a multi project build set the version of all projects:\ndef ver = semver.version\nallprojects {\n    version = ver\n}\n\n```\n\n[For the latest published version see the plugins page at Gradle.org](https://plugins.gradle.org/plugin/com.github.jmongard.git-semver-plugin)\n\n## Supported Gradle version\n\nThis plugin has been tested on Gradle 8.x and 9.x and requires Java version 17 to run.\n\n* Use version `0.16.1` if Gradle 7 is required.\n* Use version `0.13.0` if Java 8 is required.\n* Version `0.4.3` and older should work on Gradle 6.x and probably 5.x.\n\n## Versioning\n\nThe versioning system follows semantic versioning as described at [semver.org](https://semver.org/).\n\nThe plugin works by traversing the Git commit history backwards from HEAD until it finds a version tag or release commit, then calculates the new version based on conventional commit messages since that point.\n\nThe plugin recognizes [conventional commit](https://www.conventionalcommits.org/) messages (`fix:`, `feat:`, `refactor!:`, etc.) and increments the corresponding version number accordingly.\n\nBy default, the plugin groups multiple fixes/features or breaking changes into a single release. This means the major, minor, or patch number will increase by at most one compared to the previous release (excluding pre-releases). Set `groupVersionIncrements = false` if you prefer each commit to increment the version individually.\n\n### Releases\n\nThe plugin will search the commit tree until it finds a commit it interprets as a release commit with a version number. \n\n* Any commit tagged with a version number will be considered to be a release.\n* Any commit with commit message starting with `release:` \n\nThe version number should consist of three numbers separated by a dot e.g. `1.0.0`. The version number does not need to \nbe at the start of the message e.g. `release: v1.2.3` will be matched.\n\n\n### Uncommitted Changes\n\nIf no version increment has been triggered by conventional commit messages since the last release, the patch number will be increased by one to indicate development progress.\n\nIf the current version is not already a pre-release, `-SNAPSHOT` will be appended to indicate this is a development version.\n\n\n## Version format\n\nThe semantic version is accessible using the `semver` extension. \nThere is several options for getting the version: \n\n| semver extension property        | example release tagged commit  | example release with local changes | example one commits ahead of pre-release alpha.1 |\n|----------------------------------|--------------------------------|------------------------------------| -------------------------------------------------|\n| `semver.version`                 | 1.0.1                          | 1.0.2-SNAPSHOT                     | 2.0.0-alpha.2                                    |\n| `semver.infoVersion`             | 1.0.1                          | 1.0.2-SNAPSHOT                     | 2.0.0-alpha.2+001                                |\n| `semver.semVersion.toString()`   | 1.0.1+sha.1c792d5              | 1.0.2-SNAPSHOT+sha.1c792d5         | 2.0.0-alpha.2+001.sha.1c792d5                    |\n\n\n### Custom version format\n\nThere is also the possibility to customize the version string returned using:\n`semver.semVersion.toInfoVersionString(commitCountStringFormat: String = \"%03d\", shaLength: Int = 0, version2: Boolean = true, appendPreReleaseLast: Boolean = false)`\n\nIf Version2 flag is set to false, then semVer version one will be used stripping any non alpha-numeric characters from\nthe pre-release string and removing the metadata part.\n\nThe `appendPreReleaseLast` option can help when publishing to maven repositories if metadata is included but the version \nstring will not be semver compliant. \n\n* semver.version == semver.semVersion.toInfoVersionString(\"\", 0, true, false)\n* semver.infoVersion == semver.semVersion.toInfoVersionString(\"%03d\", 0, true, false)\n* semver.semVersion.toString() == semver.semVersion.toInfoVersionString(\"%03d\", 7, true, false)\n\n### Two-Digit Versioning\n\nThe plugin supports 2-digit versioning (major.minor) in addition to the standard 3-digit semantic versioning (major.minor.patch). \nThis can be useful for projects that follow a simpler versioning scheme.\n\nTo enable 2-digit versioning, set `useTwoDigitVersion = true` in your configuration.\n\n## Tasks\n\n## `printVersion`\nThis plugin adds a printVersion task, which will echo the project's calculated version\nto standard-out.\n\n````shell\n$ gradlew printVersion\n\n\u003e Task :printVersion\n10.10.0-SNAPSHOT\n````\n\n## `printInfoVersion`\nThis plugin adds a printInfoVersion task, which will echo the project's calculated version\nto standard-out including commit count.\n\n````shell\n$ gradlew printInfoVersion\n\n\u003e Task :printInfoVersion\n10.10.0-SNAPSHOT+072\n````\n\n## `printSemVersion`\nThis plugin adds a printSemVersion task, which will echo the project's calculated version\nto standard-out including commit count and SHA.\n\n````shell\n$ gradlew printSemVersion\n\n\u003e Task :printSemVersion\n10.10.0-SNAPSHOT+072.sha.18b3106\n````\n\n## `printChangeLog`\nThis plugin adds a printChangeLog task, which will format the commit messages for the current version\nand output them to standard-out. To avoid encoding problems in the console, the change log can be output\nto a UTF-8 encoded file using `--file \u003cfilename\u003e`, e.g. `./gradlew printChangeLog --file build/changelog.md`.\n\n**Note:** Use an absolute path for the filename as the working directory might not be what you expect when running\nusing the Gradle daemon. The `printChangeLog` task is currently only registered on the root project when the plugin is applied there.\n\n````shell\n$ gradlew printChangeLog\n\n\u003e Task :printChangeLog\n## What's Changed\n\n### Breaking Changes\n  - fix(#5)!: A breaking change\n\n### Bug Fixes\n  - #1: A bug fix\n  - #2: Another bug fix\n````\n[Configuring the changelog](/ChangeLog.md)\n\n## `releaseVersion`\nThe `releaseVersion` task creates both a release commit and a release tag by default. The task will fail with an error if there are uncommitted local modifications. You can modify this behavior using the following options:\n\n* **--no-tag**: Skip creating a tag (can also be set in settings using `createReleaseTag=false`)\n* **--tag**: Create a tag (default behavior, unless disabled in settings)\n* **--no-commit**: Skip creating a commit (can also be set in settings using `createReleaseCommit=false`)\n* **--commit**: Create a commit (default behavior, unless disabled in settings)\n* **--no-dirty**: Skip the dirty working directory check (can also be set in settings using `noDirtyCheck=true`)\n* **--message**=\"message\": Add a custom message to the tag and/or commit\n* **--preRelease**=\"version\": Set the pre-release identifier (e.g., `--preRelease=alpha.1`). Use `--preRelease=-` to promote a pre-release to a full release\n\n**Note:** The `releaseVersion` task is currently only registered on the root project when the plugin is applied there.\n\n## Example of how version is calculated \n\n### With setting: `groupVersionIncrements = true` (default)\n\n| Command                                       | Commit Text               | Calculated version  |\n| --------------------------------------------- | ------------------------- | ------------------- |\n| git commit -m \"Initial commit\"                | Initial commit            | 0.0.1-SNAPSHOT+001  |\n| git commit -m \"some changes\"                  | some changes              | 0.0.1-SNAPSHOT+002  |\n| gradle releaseVersion                         | release: v0.0.1           | 0.0.1               |\n| git commit -m \"some changes\"                  | some changes              | 0.0.2-SNAPSHOT+001  |\n| gradle releaseVersion                         | release: v0.0.2           | 0.0.2               |\n| git commit -m \"fix: a fix\"                    | fix: a fix                | 0.0.3-SNAPSHOT+001  |\n| git commit -m \"fix: another fix\"              | fix: another fix          | 0.0.3-SNAPSHOT+002  |\n| gradle releaseVersion                         | release: v0.0.3           | 0.0.3               |\n| git commit -m \"feat: a feature\"               | feat: a feature           | 0.1.0-SNAPSHOT+001  |\n| git commit -m \"feat: another feature\"         | feat: another feature     | 0.1.0-SNAPSHOT+002  |\n| git commit -m \"feat!: breaking feature\"       | feat!: breaking feature   | 1.0.0-SNAPSHOT+003  |\n| git commit -m \"some changes\"                  | some changes              | 1.0.0-SNAPSHOT+004  |\n| git commit -m \"feat: changes\"                 | feat: changes             | 1.0.0-SNAPSHOT+005  |\n| git commit -m \"feat: changes\"                 | feat: changes             | 1.0.0-SNAPSHOT+006  |\n| git commit -m \"fix: a fix\"                    | fix: a fix                | 1.0.0-SNAPSHOT+007  |\n| gradle releaseVersion                         | release: v1.0.0           | 1.0.0               |\n| git commit -m \"some changes\"                  | some changes              | 1.0.1-SNAPSHOT+001  |\n| gradle releaseVersion --preRelease=\"alpha.1\"  | release: v1.0.1-alpha.1   | 1.0.1-alpha.1       |\n| git commit -m \"some changes\"                  | some changes              | 1.0.1-alpha.2+001   |\n| gradle releaseVersion                         | release: v1.0.1-alpha.2   | 1.0.1-alpha.2       |\n| git commit -m \"fix: a fix\"                    | fix: a fix                | 1.0.1-alpha.3+001   |\n| git commit -m \"fix: another fix\"              | fix: another fix          | 1.0.1-alpha.3+002   |\n| git commit -m \"feat: a feature\"               | feat: a feature           | 1.1.0-alpha.1+003   |\n| gradle releaseVersion                         | release: v1.1.0-alpha.1   | 1.1.0-alpha.1       |\n| git commit -m \"feat: another feature\"         | feat: another feature     | 1.1.0-alpha.2+001   |\n| git commit -m \"feat!: breaking feature\"       | feat!: breaking feature   | 2.0.0-alpha.1+002   |\n| gradle releaseVersion --preRelease=\"-\"        | release: v2.0.0           | 2.0.0               |\n\n### With setting: `groupVersionIncrements = false`\n\n| Command                                       | Commit Text               | Calculated version |\n| --------------------------------------------- | ------------------------- | ------------------- |\n| git commit -m \"Initial commit\"                | Initial commit            | 0.0.1-SNAPSHOT+001 |\n| git commit -m \"some changes\"                  | some changes              | 0.0.1-SNAPSHOT+002 |\n| gradle releaseVersion                         | release: v0.0.1           | 0.0.1              |\n| git commit -m \"some changes\"                  | some changes              | 0.0.2-SNAPSHOT+001 |\n| gradle releaseVersion                         | release: v0.0.2           | 0.0.2              |\n| git commit -m \"fix: a fix\"                    | fix: a fix                | 0.0.3-SNAPSHOT+001 |\n| git commit -m \"fix: another fix\"              | fix: another fix          | 0.0.4-SNAPSHOT+002 |\n| gradle releaseVersion                         | release: v0.0.4           | 0.0.4              |\n| git commit -m \"feat: a feature\"               | feat: a feature           | 0.1.0-SNAPSHOT+001 |\n| git commit -m \"feat: another feature\"         | feat: another feature     | 0.2.0-SNAPSHOT+002 |\n| git commit -m \"feat!: breaking feature\"       | feat!: breaking feature   | 1.0.0-SNAPSHOT+003 |\n| git commit -m \"some changes\"                  | some changes              | 1.0.0-SNAPSHOT+004 |\n| git commit -m \"feat: changes\"                 | feat: changes             | 1.1.0-SNAPSHOT+005 |\n| git commit -m \"feat: changes\"                 | feat: changes             | 1.2.0-SNAPSHOT+006 |\n| git commit -m \"fix: a fix\"                    | fix: a fix                | 1.2.1-SNAPSHOT+007 |\n| gradle releaseVersion                         | release: v1.2.1           | 1.2.1              |\n| git commit -m \"some changes\"                  | some changes              | 1.2.2-SNAPSHOT+001 |\n| gradle releaseVersion --preRelease=\"alpha.1\"  | release: v1.2.2-alpha.1   | 1.2.2-alpha.1      |\n| git commit -m \"some changes\"                  | some changes              | 1.2.2-alpha.2+001  |\n| gradle releaseVersion                         | release: v1.2.2-alpha.2   | 1.2.2-alpha.2      |\n| git commit -m \"fix: a fix\"                    | fix: a fix                | 1.2.2-alpha.3+001  |\n| git commit -m \"fix: another fix\"              | fix: another fix          | 1.2.2-alpha.4+002  |\n| git commit -m \"feat: a feature\"               | feat: a feature           | 1.3.0-alpha.1+003  |\n| gradle releaseVersion                         | release: v1.3.0-alpha.1   | 1.3.0-alpha.1      |\n| git commit -m \"feat: another feature\"         | feat: another feature     | 1.3.0-alpha.2+001  |\n| git commit -m \"feat!: breaking feature\"       | feat!: breaking feature   | 2.0.0-alpha.1+002  |\n| gradle releaseVersion --preRelease=\"-\"        | release: v2.0.0           | 2.0.0              |\n\n## Configuration\n\nThe plugin can be configured using the `semver` extension. This needs to be done before retrieving the version:\n\n```groovy\nsemver {\n    //Example of each property with their respective default value. \n    //There is no need to set these unless you want to change the default. \n    defaultPreRelease = \"SNAPSHOT\"\n    releasePattern = \"\\\\Arelease(?:\\\\([^()]+\\\\))?:\"\n    majorPattern = \"\\\\A\\\\w+(?:\\\\([^()]+\\\\))?!:|^BREAKING[ -]CHANGE:\"\n    minorPattern = \"\\\\Afeat(?:\\\\([^()]+\\\\))?:\"\n    patchPattern = \"\\\\Afix(?:\\\\([^()]+\\\\))?:\"\n    releaseCommitTextFormat = \"release: v%s\\n\\n%s\"\n    releaseTagNameFormat = \"%s\"\n    groupVersionIncrements = true\n    noDirtyCheck = false\n    noAutoBump = false\n    noReleaseAutoBump = false\n    gitDirectory = project.projectDir\n    createReleaseCommit = true\n    createReleaseTag = true\n    metaSeparator = '+'\n    useTwoDigitVersion = false\n}\n\n//Remember to retrieve the version after plugin has been configured\nversion = semver.version\n```\n\n* **defaultPreRelease**: sets the default pre-release to use if there are commits or local modifications.\n* **releasePattern**: used to identify commits that are used as release markers.\n* **majorPattern, minorPattern and patchPattern**: used to identify conventional commits used for increasing version.\n* **releaseCommitTextFormat**: String format used by `releaseVersion` task for creating release commits. First parameter\n  is the version and second parameter is the message (if given using --message=).\n  This text should preferably match the `releasePattern`.\n* **releaseTagNameFormat**: String format used by `releaseVersion` task for creating release tags e.g. `\"v%s\"` to prefix \n  version tags with \"v\".\n* **groupVersionIncrements**: Used to disable grouping of version increments so that each commit message counts.\n* **noDirtyCheck**: Can be used to ignore all local modifications when calculating the version.\n  Disabling dirty check can also be done from the command line e.g. `gradlew -PnoDirtyCheck=true someOtherTask`.\n* **noAutoBump**: If enabled only commits matching majorPattern, minorPattern or patchPattern will increase the version.\n  The default behavior for the plugin is to assume you have begun the work on the next release for any commit you do\n  after the last release. The patch level (or pre-release level, if the last release was a pre-release) of the version\n  will be incremented by one if not already incremented by **majorPattern,  minorPattern or patchPattern**.\n  (This option does not apply to the release task.)\n* **noReleaseAutoBump**: If enabled, and no commit matches majorPattern, minorPattern, or patchPattern, then the release task will not increase the version. \n* **gitDirectory**: The directory where the git repo can be found. \n* **createReleaseTag**: If a release tag should be created when running the release task. Setting this to false\n  has the same effect as the --no-tag flag.\n* **createReleaseCommit**: If a release commit should be created when running the release task. Setting this to false\n  has the same effect as the --no-commit flag.\n* **metaSeparator**: The character to use to separate build metadata from the version when printing info version.\n* **useTwoDigitVersion**: If the version should be two digits instead of three.\n\nPatterns is matched using [java regular expressions](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) \nwith IGNORE_CASE and MULTILINE options enabled.\n\n## Continuous Integration\nThe plugin calculates the version using the commit tree. Make sure you check out all commits relevant and not just\na shallow copy.\n\n[GitHub Actions example project](https://github.com/jmongard/Git.SemVersioning.Gradle.Actions-Example)\n\n### GitHub Actions checkout example\n```yaml\n- uses: actions/checkout@v3\n  with:\n    fetch-depth: 0\n```\n\n### GitHub Actions create release example\n```yaml\n  - name: Create GitHub release\n    env:\n      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n    run: |\n      tag=$(git describe --tags --abbrev=0)\n      version=$(./gradlew -q printVersion)\n       ./gradlew -q printChangeLog | gh release create $tag -d -t \"Example Project $version\" -F -\n```\n\n\n## Version 0.x.x\nBreaking changes for version 0.x.x do not automatically increase the major version. If you want to increase the major\nversion, create a release commit manually and set the desired version number e.g.\n\n```\ngit commit -m \"release: 1.0.0\" --allow-empty \n```\n\n\n## Limitations\n\n### Reverts\nThe plugin does not handle commits reverting previous commits and referring to the reverted commit in the commit message. \nSet the version to the correct version after reverting as in the example above. \n\n\n# Resources\n\n* [Semantic Versioning](https://semver.org/)\n* [Conventional Commit](https://www.conventionalcommits.org/)\n* [Angular Git Commit Guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmongard%2Fgit.semversioning.gradle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmongard%2Fgit.semversioning.gradle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmongard%2Fgit.semversioning.gradle/lists"}