Semantic Version Plugin for Gradle
Clone or download
Latest commit 2cbea71 Nov 27, 2018

README.md

License (3-Clause BSD) CircleCI

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=

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

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)
    ...
}

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

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.buildmeta The build metatdata version
version.prerelease.prefix The pre-release prefix -
version.buildmeta.prefix The build metadata prefix +
version.separator The version separator. .

The version number is built as follows:

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

for example:

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

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

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
    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=

The following semver properties are available:

Property Description Default
properties The properties file. version.properties
majorKey The major property key. major
minorKey The minor property key. minor
patchKey The patch property key. patch
preReleaseKey The pre-release property key. preRelease
preReleasePrefixKey The build pre-release prefix key. preReleasePrefix
buildMetaKey The build metadata property key. buildMeta
buildMetaPrefixKey The build metadata prefix property key. buildMetaPrefix
separatorKey The separator property key. 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=

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.