A simple Git tag-based versioning plugin
OTHER License
simplversion is a simple Git-based versioning plugin.
This plugin is meant for maintainer-controlled versioning -- releases are only published on tagged commits (without any uncommitted changes). This gives flexibility to the maintainer in making releases, as opposed to a more automated versioning setup which builds and publishes all commits as releases.
The version calculated by this plugin is based on Git tags, and tries its best to be compatible with the Semantic
Versioning specification, v2.0.0. A notable caveat is that pre-release versions have both the pre-release
version and the -SNAPSHOT
suffix in the full version.
This plugin is available on the Gradle Plugin Portal; you do not need to add an additional repository.
Apply the dev.sciwhiz12.gradle.simplversion
plugin:
plugins {
id 'dev.sciwhiz12.gradle.simplversion' version '0.2.0' // Replace version with the latest release
}
Configure the versions
extension, and configure your project to use the version from the extension:
versions {
// Defaults included with the plugin, do not include unless customizing
stripBranchPrefix = true
incrementPositionIfSnapshot(-2) // Second to last version: #.#.(#).#
skipIncrementForClassifiers('alpha', 'beta', 'pre', 'rc')
}
// Set project version
version = versions.version
Optionally, if publishing: Configure the publication to use the simple version from the extension:
publishing {
publications {
mavenJava { // Example publication
// ...
version = versions.simpleVersion
}
}
}
By default, the following configuration options are set:
The branch name is stripped from the raw version.
No dirty workspace prefix is configured.
The second-to-last position in the raw version is incremented for snapshot versions.
The snapshot increment is skipped when the following classifiers (prefixed with a -
) are found in the raw version:
alpha
, beta
, pre
, and rc
.
For example, 1.3.0-beta
, 2.4.6-rc2
, and 5.0.0-pre7
will not be incremented, even if it is a snapshot version.
Some terms used in the plugin:
raw version: the version as taken from the nearest reachable tag, after stripping the branch and custom prefixes and removing parts that match the stripping pattern
full version or simply version: the raw version and any calculated classifiers
classifiers: when part of the raw version, any text after the first hyphen (-
). when part of the full version,
metadata calculated by the plugin that is separated from the raw version with a hyphen (-
).
Classifiers currently used by the plugin are as follows:
-SNAPSHOT
- a Maven-recognized version classifier/suffix that is appended for snapshot versions+<commit ID>
- the abbreviated commit ID, separated using a plus sign as indicated in SemVer 2.0.0, whenversions
extensionThe versions
project-level extension configures the plugin and provides the calculated version information. The
extension's class is VersionExtension
, and the version information is represented by the VersionInformation
class.
For additional details, consult the documented source code.
This plugin is configured to strip parts of the raw version based on a mix of configuration from the user and hardcoded defaults. Stripping is done in four parts:
First, the branch name prefix, separated from the rest of the raw version with a hyphen (-
) or forward slash (/
),
is removed when the extension is configured to do so through the stripBranchPrefix
boolean property.
Second, any custom prefixes, separated from the rest of the raw version with a hyphen (-
) or forward slash (/
),
are removed according to the customPrefixes
string list property.
Third, the stripping pattern is matched against the raw version and any matching parts are removed, as configured
by the stripPattern
regular expression pattern property.
It should be noted that only the parts matched by the pattern are removed. When creating the pattern, users should
take care to include any separator between the parts and the rest of the raw version. Users should also use the line
start boundary matcher (^
) if they are stripping out a prefix, to ensure no accidental removals in the middle of the
raw version happen.
Fourth, the v
prefix is removed from the raw version if present.
Snapshot versions may be configured to increment an integer position in the raw version. This allows in-development versions to attempt to match to the next likely version to be released.
The snapshotIncrementPosition
integer property (which can be set using the incrementPositionIfSnapshot
method)
configures the position to be incremented. Positions are counted by separating the raw version into parts by first
taking the part of the raw version before any hyphens (-
), plus signs (+
), or underscores (_
), then splitting that
into parts based on the dot/period (.
).
For example, the version 1.4.5.3-pre3+2
will be first cleaned up into 1.2.5.4
, and then split into four parts: 1
,
2
, 5
, and 3
.
The values of the property are interpreted as follows:
2
would mean the second position would be incremented: 2
becomes 3
.-2
would mean the second-to-last (third) position would be incremented: 5
becomes 6
.The skipIncrement
predicate allows customizing when the above incrementing behavior is skipped for certain snapshot
versions. The predicate is provided with a VersionInformation
encapsulating the current version information, with the
notable caveat that it is not the final version information, as the raw version contains the version before any
increment and the classifiers do not contain the -SNAPSHOT
suffix.
For convenience, the skipIncrementForClassifiers
method is provided to configure a predicate which skips the increment
if any of the given classifiers (along with a -
prepended before them) are found anywhere in the raw version. For
example, passing in pre
would mean it would look for the string -pre
in any place of the raw version.
The dirtySuffix
string property configures a suffix to be appended if the current workspace is dirty -- if there are
any uncommitted (including untracked) changes. This may be useful in ensuring that any artifacts built from a dirty
workspace are appropriately marked in their filename, reducing possible confusion. For example, a dirty suffix of
.dirty
in a workspace on a commit tagged 1.5.0
and commit afbc345
would result in a full version of
1.5.0+afbc345.dirty
.
The version information is available through the extension's versionInfo
property, as a provider. The provider's value
is calculated once on the first query to the provider , and all properties in the extension are finalized once the
version is calculated. For convenience, the properties available on the VersionInformation
object are available on
the VersionExtension
as well, which call the provider and retrieve the corresponding property.
version
- the full versionrawVersion
- the raw version, without any classifierssimpleVersion
- the simple version, which is composed of the raw version and the -SNAPSHOT
classifier for asnapshot
- a boolean for whether it is a snapshot versionclassifiers
- the classifiers, as a string which can be appended to the raw version (forming the full version)fullCommitId
- the full SHA-1 (or SHA-256) ID of the commit, in lowercase hexadecimalabbreivatedCommitId
- the abbreviated SHA-1 (or SHA-256) ID of the commit, in lowercase hexadecimal
commitTimestamp
- the timestamp of the commit, in ISO-8601 extended offset date-time format (1970-01-01T00:00:00+00:00
)This project is licensed under the MIT License. See the LICENSE.txt
file for the full license text.