Gradle Versioning

A Gradle plugin for applying project version from Git tags.

Made with ❤️ by Widen.

Plugin page

Overview

This plugin moves your project version out of the build.gradle file, and instead uses Git tags as the canonical source of truth for version numbers. This makes it easier to maintain nice version numbers and eliminate "Bump version" commits.

Version numbers that are generated are based off of the output of running git describe --tags in your repository with a few minor changes. Generally the version number syntax follows the below scheme:

(last tagged version) + (commits since last tag) - (current commit hash) (-dirty if dirty)

Usage

Apply the plugin using the standard plugins configuration:

plugins {
    id 'com.widen.versioning' version '<current version>'
}

Once the plugin is applied, your project will now infer the current project version automatically based on the most recent release in your Git repository. Be sure to remove any version '<version>' lines in your build.gradle, or the version number will get overwritten.

Configuration

The default settings should be good enough for most projects, but there are a couple of settings you can set to change how versions are generated if you need them. For example, if your Git tags are prefixed with a v, you can have versions generated only from such tags and then have the prefix removed using the tagPrefix setting:

versioning {
    tagPrefix = 'v'
}

Below are all the available settings and what they do.

Name	Default value	Description
tagPrefix	null	A prefix that tags must start with in order to be considered a version tag. The prefix is removed from the final version string.
excludeTags	null	A regular expression for tags that should be ignored.
useCommitHashDefault	true	Whether the abbreviated commit hash should be used as a version number if no tags are available.
initialVersion	"0.0.0"	An initial version number to use if no tags are available. Can also be overridden by setting version manually.
dirtyMark	true	Whether a -dirty suffix should be added to the version string if the Git working directory is dirty.

Automatic publishing

If you are using Travis, the following configuration works quite nicely:

after_success:
  - test "$TRAVIS_PULL_REQUEST" = false && ./gradlew publish

Semantic versioning

Version numbers generated by this plugin do follow the Semantic Versioning 2.0.0 spec, but with a caveat. SemVer does not have the concept of post-release versions or semantically meaningful build numbers, so we put the current build number into the version build metadata (everything following the +). This works, but most SemVer parsers ignore this part of the version in comparisons (as the spec says it SHOULD be ignored), so be careful if you are doing any parsing on the version number yourself.

Releasing this plugin

This Gradle plugin uses the most recent version of itself to determine its next version, so preparing a new release of gradle-versioning is much like releasing a normal project using this plugin. Simply publish a new tag in the Git repository, and a build will be published to the Maven repository automatically.

License

Available under the Apache-2.0 license. See the license file for details.