scmversion gradle plugin

Your software should be versioned, and the assigned version numbers should be represented somewhere in your source control management. This plugin detects tags of your source control management matching a given pattern, extracts the version number, and makes it available both to Gradle and optionally your program. It rids you of the nuisance to keep the version number in your scm and the version number for your deployment in sync.

The plugin is fully self-contained, i.e. it does not rely on the availability of any version management binaries on the system.

Usage, Supported SCMs

The plugin is applied as given below:

Gradle 2.1 or later:

plugins {
  id 'de.ploing.scmversion' version '0.6.6'
}

Older versions of Gradle:

buildscript {
  repositories {
    maven {
      url 'https://plugins.gradle.org/m2/'
    }
  }
  dependencies {
    classpath 'gradle.plugin.de.ploing.gradle:scmversion-gradle-plugin:0.6.6'
  }
}

apply plugin: 'de.ploing.scmversion'

In contrast to earlier versions, the scm in use is automatically detected, no more need to have separate plugins for different scms.

Currently, only git is supported. The plugin can be easily extended to new scm systems.

Usage

Set Gradle’s version property

When the plugin is applied, it will replace the version property of gradle with the one determined from the scm tags:

If the current scm state is on a revision with a version tag, and if no files are modified (i.e. the repo is not dirty), the version number from the version tag is used
Otherwise, the highest version number from a tag is determined, the least significant number is increased by one and appended by the snapshot suffix
If no version tag is found, the version number 0 is assumed

The version property is e.g. used by the maven plugin for determining the version information for assembled jar files.

The task setVersion is provided for this purpose; it is automatically called after setting up the project.

Write scm information to property file

If a property filename is configured, the plugin will write the current scm status to a property file:

scmversion {
  propertyFilename = 'scmversion.properties'
}

The Gradle task createVersionFile will put a file named scmversion.properties to the directory build/resources/main. The property file may look like the following:

#SCM version information
version=1.0.3-SNAPSHOT
rev=d460689dd68071442beeee4d984a85f9996d7a37
dirty=false

Custom revision tag pattern

The format of version tags can be customized using a regular expression; the default looks like the following:

scmversion {
  releaseTagPattern = 'version-([0-9.]*)'
}

The regular expression fulfills two purposes:

Determine if the tag is a version tag
Extract the version number

The matched part will be used as version number; if you choose to use an alternate version number scheme not matching the regex above: Read on :-)

Custom version number scheme

The default configuration handles version number consisting of an arbitrary number of version number parts separated by a dot (e.g. "1.0" or "2.0.3"). If you choose to use a different pattern, you not only have to adapt the `releaseTagPattern`regex, but re-implement the following two closures:

versionComparator: A closure taking two version numbers as parameters. It returns -1/0/1 if the first version number is smaller/equal/larger than the second.
incVersion: A closure taking one version number as parameter and returns a new version string. The purpose of this closure is to determine the version string used for snapshot versions, i.e. the "next" version after the latest one.

scm root outside project root

By default, the plugin assumes that the project root equals the scm root. This is true in most standard cases, but a multiproject setup hosted in one scm repository breaks this assumption. If your scm root lies outside your project, you can tell the plugin to search for it above the project root directory:

scmversion {
  scmRootSearchDepth = 2
}

The parameter gives the maximum number of directory levels to search for the scm root. The example given above means that the scm root is first expected in the project root; if not found, one directory level above the project root is checked; if still not found, the search ascends another directory level. If no scm is present here, the plugin will throw an error.

Accessing `project.version` within the build script

The version is set by executing a task after initializing the project. This means that the version variable is not (yet) set to the desired value when using it e.g. in string concatenations. To allow access to the calculated version, the version field is set to a proxy object, which determines the version in its toString method on demand. After project initialization, the proxy object is replaced by a regular string.

Bear in mind that the proxy object can only reflect the current state; this means that the order of your statements is of importance. You have to make sure that this plugin is properly configured before you access the version information.

License

Licensed under the Apache License, Version 2.0.

Skyr/scmversion-gradle-plugin