Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ethauvin/semver-gradle
Semantic Version Plugin for Gradle
https://github.com/ethauvin/semver-gradle
auto-increment gradle java kotlin plugin semantic semver version versioning
Last synced: 3 months ago
JSON representation
Semantic Version Plugin for Gradle
- Host: GitHub
- URL: https://github.com/ethauvin/semver-gradle
- Owner: ethauvin
- License: bsd-3-clause
- Created: 2018-06-30T03:14:34.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-02-12T04:01:08.000Z (12 months ago)
- Last Synced: 2024-08-01T19:54:08.265Z (6 months ago)
- Topics: auto-increment, gradle, java, kotlin, plugin, semantic, semver, version, versioning
- Language: Kotlin
- Homepage:
- Size: 711 KB
- Stars: 23
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.TXT
Awesome Lists containing this project
README
[](http://opensource.org/licenses/BSD-3-Clause) [](https://sonarcloud.io/dashboard?id=ethauvin_semver-gradle) [](https://travis-ci.com/ethauvin/semver-gradle) [](https://circleci.com/gh/ethauvin/semver-gradle/tree/master) [](https://plugins.gradle.org/plugin/net.thauvin.erik.gradle.semver)
# Semantic Version Plugin for Gradle
A [Semantic Version](https://semver.org) Plugin for [Gradle](https://gradle.org) 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__](https://github.com/ethauvin/semver).
## Using the plugin
The plugin is published to the Plugin Portal; see instructions there: [__net.thauvin.erik.gradle.semver__](https://plugins.gradle.org/plugin/net.thauvin.erik.gradle.semver)
## Version Properties File
By default, a [properties](https://docs.oracle.com/javase/tutorial/essential/environment/properties.html) file named `version.properties` will be created when Gradle is run:
```ini
#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](https://github.com/ethauvin/semver-gradle/tree/master/examples/java), [Kotlin](https://github.com/ethauvin/semver-gradle/tree/master/examples/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](#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
```sh
./gradlew incrementPatch ...
```
or in your `gradle.build` file:
```gradle
someTask {
dependsOn(incrementPatch)
...
}
```
- __Examples__: [Java](https://github.com/ethauvin/semver-gradle/tree/master/examples/java), [Kotlin](https://github.com/ethauvin/semver-gradle/tree/master/examples/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:
```gradle
incrementBuildMeta {
doFirst {
buildMeta = new Date().format("yyyyMMddHHmmss")
}
}
```
```bash
./gradlew incrementBuildMeta
...
> Task :incrementBuildMeta
Version: 1.0.16-beta+20180713143416
```
Or to set the build metadata to a custom formatted number with increment:
```gradle
incrementBuildMeta {
doFirst {
buildMeta = sprintf("%03d", (buildMeta as Integer) + 1)
}
}
```
```bash
./gradlew incrementBuildMeta
...
> Task :incrementBuildMeta
Version: 1.0.16-beta+002
```
- __Examples__: [Java](https://github.com/ethauvin/semver-gradle/tree/master/examples/java), [Kotlin](https://github.com/ethauvin/semver-gradle/tree/master/examples/kotlin)
## Command Line
The `major`, `minor`, `patch`, `prerelease` and `buildmeta` versions can also be set via the command line:
```bash
./gradlew -Dversion.prerelease=beta -Dversion.buildmeta= ...
```
```ini
#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:
```sh
./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:
```ini
#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](https://github.com/ethauvin/semver-gradle/tree/master/examples/java), [Kotlin](https://github.com/ethauvin/semver-gradle/tree/master/examples/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:
```gradle
semver {
properties = "my.version" // read and save properties in "my.version"
}
```
or using different property keys for the version data:
```gradle
semver {
keysPrefix = "" // no prefix
semverKey = "version"
majorKey = "maj"
minorKey = "min"
patchKey = "build"
preReleaseKey = "rel"
buildMetaKey = "meta"
}
```
which would match the data in `my.version`:
```ini
#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:
```gradle
semver {
properties = "test.properties"
keysPrefix = "test."
}
```
```ini
#test.properties
test.major=1
test.minor=0
test.patch=0
test.prerelease=
test.buildmeta=
test.semver=1.0.0
```
- __Examples__: [Java](https://github.com/ethauvin/semver-gradle/tree/master/examples/java), [Kotlin](https://github.com/ethauvin/semver-gradle/tree/master/examples/kotlin)
### Semver Extension Properties
The values stored in the version properties file can individually be accessed using the `semver` extension, for example:
```gradle
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:
```gradle
task foo() {
doFirst {
println project.version
}
}
```
or if absolutely necessary, at the end of the configuration stage in a `project.afterEvaluate` block:
```gradle
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__](https://github.com/ethauvin/semver).
There are also full [examples](https://github.com/ethauvin/semver-gradle/tree/master/examples/annotation-processor) in both [Java](https://github.com/ethauvin/semver-gradle/tree/master/examples/annotation-processor/java) and [Kotlin](https://github.com/ethauvin/semver-gradle/tree/master/examples/annotation-processor/kotlin) showing how to use both the plugin and annotation processor concurrently.