Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/widen/gradle-versioning

A Gradle plugin for applying project version from Git tags
https://github.com/widen/gradle-versioning

gradle gradle-plugin versioning

Last synced: 3 months ago
JSON representation

A Gradle plugin for applying project version from Git tags

Awesome Lists containing this project

README 

        
# Gradle Versioning



[![Build Status](https://badge.buildkite.com/7fe00ad3adc6015d2bcf4325e8b470edfb67f283fa9361c9a1.svg)](https://buildkite.com/widen/gradle-versioning)



A Gradle plugin for applying project version from Git tags.



Made with :heart: by Widen.



[Plugin page](https://plugins.gradle.org/plugin/com.widen.versioning)



## 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 ''

}

```



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 ''` 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:



```groovy

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:



```yml

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](https://semver.org/spec/v2.0.0.html), 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](LICENSE) for details.