Git Semantic Versioning Plugin for Gradle

A 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.

Usage

Apply the plugin using standard Gradle convention and set the version of the project:

plugins {
    id 'com.github.jmongard.git-semver-plugin' version '<current version>'
}

//semver { ... } // Optionally add configuration for the plugin before getting the version

//Set the version for the current project:
version = semver.version

//Or in a multi project build set the version of all projects:
def ver = semver.version
allprojects {
    version = ver
}

For the latest published version see the plugins page at Gradle.org

Supported Gradle version

This plugin has been tested on Gradle 8.x and 9.x and requires Java version 17 to run.

• Use version 0.16.1 if Gradle 7 is required.
• Use version 0.13.0 if Java 8 is required.
• Version 0.4.3 and older should work on Gradle 6.x and probably 5.x.

Versioning

The versioning system follows semantic versioning as described at semver.org.

The 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.

The plugin recognizes conventional commit messages (fix:, feat:, refactor!:, etc.) and increments the corresponding version number accordingly.

By 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.

Releases

The plugin will search the commit tree until it finds a commit it interprets as a release commit with a version number.

• Any commit tagged with a version number will be considered to be a release.
• Any commit with commit message starting with release:

The version number should consist of three numbers separated by a dot e.g. 1.0.0. The version number does not need to be at the start of the message e.g. release: v1.2.3 will be matched.

Uncommitted Changes

If 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.

If the current version is not already a pre-release, -SNAPSHOT will be appended to indicate this is a development version.

Version format

The semantic version is accessible using the semver extension. There is several options for getting the version:

| semver extension property | example release tagged commit | example release with local changes | example one commits ahead of pre-release alpha.1 | |----------------------------------|--------------------------------|------------------------------------| -------------------------------------------------| | semver.version | 1.0.1 | 1.0.2-SNAPSHOT | 2.0.0-alpha.2 | | semver.infoVersion | 1.0.1 | 1.0.2-SNAPSHOT | 2.0.0-alpha.2+001 | | semver.semVersion.toString() | 1.0.1+sha.1c792d5 | 1.0.2-SNAPSHOT+sha.1c792d5 | 2.0.0-alpha.2+001.sha.1c792d5 |

Custom version format

There is also the possibility to customize the version string returned using: semver.semVersion.toInfoVersionString(commitCountStringFormat: String = "%03d", shaLength: Int = 0, version2: Boolean = true, appendPreReleaseLast: Boolean = false)

If Version2 flag is set to false, then semVer version one will be used stripping any non alpha-numeric characters from the pre-release string and removing the metadata part.

The appendPreReleaseLast option can help when publishing to maven repositories if metadata is included but the version string will not be semver compliant.

• semver.version == semver.semVersion.toInfoVersionString("", 0, true, false)
• semver.infoVersion == semver.semVersion.toInfoVersionString("%03d", 0, true, false)
• semver.semVersion.toString() == semver.semVersion.toInfoVersionString("%03d", 7, true, false)

Two-Digit Versioning

The plugin supports 2-digit versioning (major.minor) in addition to the standard 3-digit semantic versioning (major.minor.patch). This can be useful for projects that follow a simpler versioning scheme.

To enable 2-digit versioning, set useTwoDigitVersion = true in your configuration.

Tasks

printVersion

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

$ gradlew printVersion

> Task :printVersion
10.10.0-SNAPSHOT

printInfoVersion

This plugin adds a printInfoVersion task, which will echo the project's calculated version to standard-out including commit count.

$ gradlew printInfoVersion

> Task :printInfoVersion
10.10.0-SNAPSHOT+072

printSemVersion

This plugin adds a printSemVersion task, which will echo the project's calculated version to standard-out including commit count and SHA.

$ gradlew printSemVersion

> Task :printSemVersion
10.10.0-SNAPSHOT+072.sha.18b3106

printChangeLog

This plugin adds a printChangeLog task, which will format the commit messages for the current version and output them to standard-out. To avoid encoding problems in the console, the change log can be output to a UTF-8 encoded file using --file <filename>, e.g. ./gradlew printChangeLog --file build/changelog.md.

Note: Use an absolute path for the filename as the working directory might not be what you expect when running using the Gradle daemon. The printChangeLog task is currently only registered on the root project when the plugin is applied there.

$ gradlew printChangeLog

> Task :printChangeLog
## What's Changed

### Breaking Changes
  - fix(#5)!: A breaking change

### Bug Fixes
  - #1: A bug fix
  - #2: Another bug fix

Configuring the changelog

releaseVersion

The 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:

• --no-tag: Skip creating a tag (can also be set in settings using createReleaseTag=false)
• --tag: Create a tag (default behavior, unless disabled in settings)
• --no-commit: Skip creating a commit (can also be set in settings using createReleaseCommit=false)
• --commit: Create a commit (default behavior, unless disabled in settings)
• --no-dirty: Skip the dirty working directory check (can also be set in settings using noDirtyCheck=true)
• --message="message": Add a custom message to the tag and/or commit
• --preRelease="version": Set the pre-release identifier (e.g., --preRelease=alpha.1). Use --preRelease=- to promote a pre-release to a full release

Note: The releaseVersion task is currently only registered on the root project when the plugin is applied there.

Example of how version is calculated

With setting: groupVersionIncrements = true (default)

| Command | Commit Text | Calculated version | | --------------------------------------------- | ------------------------- | ------------------- | | git commit -m "Initial commit" | Initial commit | 0.0.1-SNAPSHOT+001 | | git commit -m "some changes" | some changes | 0.0.1-SNAPSHOT+002 | | gradle releaseVersion | release: v0.0.1 | 0.0.1 | | git commit -m "some changes" | some changes | 0.0.2-SNAPSHOT+001 | | gradle releaseVersion | release: v0.0.2 | 0.0.2 | | git commit -m "fix: a fix" | fix: a fix | 0.0.3-SNAPSHOT+001 | | git commit -m "fix: another fix" | fix: another fix | 0.0.3-SNAPSHOT+002 | | gradle releaseVersion | release: v0.0.3 | 0.0.3 | | git commit -m "feat: a feature" | feat: a feature | 0.1.0-SNAPSHOT+001 | | git commit -m "feat: another feature" | feat: another feature | 0.1.0-SNAPSHOT+002 | | git commit -m "feat!: breaking feature" | feat!: breaking feature | 1.0.0-SNAPSHOT+003 | | git commit -m "some changes"