Semantic Version Plugin for Gradle

A Semantic Version Plugin for Gradle that manages a project version via a properties file, and provide tasks to automatically increment major, minor, patch and build version numbers.

The plugin can be used in conjunction with the Semantic Version Annotation Processor.

Using the plugin

The plugin is published to the Plugin Portal; see instructions there: net.thauvin.erik.gradle.semver

Version Properties File

By default, a properties file named version.properties will be created when Gradle is run:

#version.properties
version.major=1
version.minor=0
version.patch=0
version.prerelease=
version.buildmeta=
version.semver=1.0.0

To change the version of your project, remove the version from build.gradle and simply edit the version properties file to match your version number.

• Examples: Java, Kotlin

If you need to change the properties file or name of the properties keys to match your own build environment. Please see the Configuration section.

Increment Version Tasks

incrementMajor, incrementMinor and incrementPatch

The incrementMajor, incrementMinor and incrementPatch tasks are available to automatically increment their respective and reset lower counterpart version numbers.

• incrementMajor will increment the major and set the minor and patch versions to 0.
• incrementMinor will increment the minor and set the path version to 0.

Examples

./gradlew incrementPatch ...

or in your gradle.build file:

someTask {
    dependsOn(incrementPatch)
    ...
}

• Examples: Java, Kotlin

incrementBuildMeta

The incrementBuildMeta task is available to set the build metadata version to a custom calculated value.

Examples:

To set the build metadata to a custom formatted date:

incrementBuildMeta {
    doFirst {
        buildMeta = new Date().format("yyyyMMddHHmmss")
    }
}

./gradlew incrementBuildMeta

...

> Task :incrementBuildMeta
Version: 1.0.16-beta+20180713143416

Or to set the build metadata to a custom formatted number with increment:

incrementBuildMeta {
    doFirst {
        buildMeta = sprintf("%03d", (buildMeta as Integer) + 1)
    }
}

./gradlew incrementBuildMeta

...

> Task :incrementBuildMeta
Version: 1.0.16-beta+002

• Examples: Java, Kotlin

Command Line

The major, minor, patch, prerelease and buildmeta versions can also be set via the command line:

./gradlew -Dversion.prerelease=beta -Dversion.buildmeta= ...

#version.properties
version.major=1
version.minor=0
version.patch=0
version.prerelease=beta
version.buildmeta=
version.semver=1.0.0-beta

The full semantic version can also be specified via the semver property:

./gradlew -Dversion.semver=1.0.0-beta ...

If a version cannot be parsed your build will fail.

Configuration

Version File Properties

The following default properties are recognized:

Property	Description	Default
version.major	The major version.	1
version.minor	The minor version.	0
version.patch	The patch version.	0
version.prerelease	The pre-release version
version.prerelease.prefix	The pre-release prefix	-
version.buildmeta	The build metatdata version
version.buildmeta.prefix	The build metadata prefix	+
version.separator	The version separator.	.

The version number is built as follows:

version.major version.separator version.minor version.separator version.patch [ version.prerelease.prefix version.prerelease ] [ version.prerelease.prefix version.buildmeta ]

For reference, it is automatically included in the version.semver property.

for example:

#version.properties
version.major=1
version.minor=0
version.patch=0
version.prerelease=beta
version.buildmeta=exp.sha.5114f85
version.semver=1.0.0-beta+exp.sha.5114f85

project.version will be 1.0.0-beta+exp.sha.5114f85 in Gradle.

• Examples: Java, Kotlin

Semver

In a Gradle build file, the semver block is used to configure how the plugin will read/write the version properties file. In most cases it is not needed.

But, for example, if you wanted to save the version properties in a different file:

semver {
    properties = "my.version" // read and save properties in "my.version"
}

or using different property keys for the version data:

semver {
    keysPrefix = "" // no prefix
    semverKey = "version"
    majorKey = "maj"
    minorKey = "min"
    patchKey = "build"
    preReleaseKey = "rel"
    buildMetaKey = "meta"
}

which would match the data in my.version:

#my.version
maj=1
min=0
build=0
rel=beta
meta=
version=1.0.0-beta

The following semver properties are available:

Property	Description	Default
properties	The properties file.	version.properties
semverKey	The semver property key.	version.semver
majorKey	The major property key.	version.major
minorKey	The minor property key.	version.minor
patchKey	The patch property key.	version.patch
preReleaseKey	The pre-release property key.	version.prerelease
preReleasePrefixKey	The build pre-release prefix key.	version.prerelease.prefix
buildMetaKey	The build metadata property key.	version.buildmeta
buildMetaPrefixKey	The build metadata prefix property key.	version.buildmeta.prefix
separatorKey	The separator property key.	version.separator
keysPrefix	The prefix for all property keys.	version.

In order to quickly support multiple projects. The keysPrefix property is available to set all properties keys prefixes at once:

semver {
    properties = "test.properties"
    keysPrefix = "test."
}

#test.properties
test.major=1
test.minor=0
test.patch=0
test.prerelease=
test.buildmeta=
test.semver=1.0.0

• Examples: Java, Kotlin

Semver Extension Properties

The values stored in the version properties file can individually be accessed using the semver extension, for example:

    fooTask {
        doFirst {
            println "Build: $semver.buildMeta"
        }
    }

The semver extension properties are:

Property	Description
semver.semver	The full semantic version.
semver.version	Same as semver.semver.
semver.major	The major version.
semver.minor	The minor version.
semver.patch	The patch version.
semver.preRelease	The pre-release version
semver.preReleasePrefix	The pre-release prefix
semver.buildMeta	The build metatdata version
semver.buildMetaPrefix	The build metadata prefix
semver.separator	The version separator.

Version is "unspecified"

This is a common problem stemming from the configuration and build phases in Gradle.

It is always preferable to access to version during the execution stage, in a doFirst or doLast closure within your tasks:

task foo() {
    doFirst {
        println project.version
    }
}

or if absolutely necessary, at the end of the configuration stage in a project.afterEvaluate block:

foo {
    project.afterEvaluate {
        println project.version
    }
}

Source Code Generation

If you'd like to incorporate the version number data into your source code, please have a look at the Semantic Version Annotation Processor.

There are also full examples in both Java and Kotlin showing how to use both the plugin and annotation processor concurrently.