Set projects versions based on git tags and following semantic versioning.
Inspired on Reckon but centered on supporting multi-project
versions and combine normal stages with snapshot stage.
In order to support configuration cache or project isolation the plugin must be applied to each
project or using the settings plugin. Avoid using allprojects or subprojects.
// build.gradle.kts
plugins {
id("com.javiersc.semver") version "$version"
}It is possible to apply the plugin to all projects if the plugin is applied in the settings.gradle
or settings.gradle.kts file:
// settings.gradle.kts
plugins {
id("com.javiersc.semver") version "$version"
}Check documented examples or test examples to understand easily how it works.
There are three project properties which the plugin uses to detect automatically the current version
based on the last tag in the current branch: semver.stage, semver.scope and semver.tagPrefix.
They can be set via CLI, for example:
./gradlew "-Psemver.stage=final" "-Psemver.scope=major" "-Psemver.tagPrefix=v"semver.stageindicates the stage to be changed, for example,alphasemver.scopeindicates the scope to be changed, for example,patchsemver.tagPrefixis used to know which version is going to be changed based on the tag prefix, for examplev. If the projects have different tag prefix, it is necessary to disambiguate which version is going to be bumped.
Default values:
| default value | Optional | |
|---|---|---|
| stage | auto |
Yes* |
| scope | auto |
Yes* |
| tagPrefix | auto |
Yes* |
Depends on the use case*
semver {
isEnabled.set(true)
tagPrefix.set("")
commitsMaxCount.set(-1)
gitDir.set(rootDir.resolve(".git"))
}
tasks.register("printLastCommitHash") {
doLast {
println(semver.commits.get().last().hash)
}
}- Default values:
| default value | |
|---|---|
| isEnabled | true |
| tagPrefix | , empty string |
| commitsMaxCount | -1 |
| gitDir | rootDir.resolve(".git") |
| version | calculated version based on the last git tag and other inputs |
tagPrefix is used to asociate a project version with a tag prefix, and it allows having different
versions in multi-project builds.
An example can be setting the extension prefix to v in a specific project A and the last tags in
the last commit are: v1.0.0 and w3.0.1. The project A version is v1.0.0. If a project B sets
the prefix to w, the project B version is w3.0.1.
In order to improve the performance on large repositories with a lot of commits, it is possible to
limit the number of commits to be checked via commitsMaxCount. By default, it is -1 which means
that all commits are checked.
semver contains commits: Provider<List<Commit>> to get the commits in the current branch and the
associated tags to each one which can be useful in some use cases.
"-Psemver.tagPrefix=v"semver.tagPrefix=vIf it is necessary to bump the project version, for example to v3.0.2 from v3.0.1, but at same
time there are more project with different prefixes, the plugin needs to know which tag prefix is
going to be bumped, so semver.tagPrefix property is the solution to that problem.
To get it working:
./gradlew "-Psemver.scope=patch" "-Psemver.tagPrefix=v"It is possible to set the project tag prefix via Gradle property if some third-party plugin requires the version in configuration phase. This property is:
semver.project.tagPrefix=vAs it can be useful to change the number of commits to be checked, it is possible to set it via properties too:
semver.commitsMaxCount=100Or in the CLI:
./gradlew "-Psemver.commitsMaxCount=100"The semver extension has a mapVersion function which allows to map the version easily:
// if last tag is v3.0.1, and the Kotlin version is 1.9.0,
// the version will be `v3.0.1+1.9.0`
semver {
tagPrefix.set("v")
mapVersion { gradleVersion: GradleVersion ->
val kotlinVersion: String = getKotlinPluginVersion()
"${gradleVersion.copy(metadata = kotlinVersion)}"
}
}If it possible to force an override of the version:
semver {
version.set("1.0.0")
}If all projects are not using a tag prefix, or in other words, the tag prefix is empty, both the property in the extension and the project property via CLI or
gradle.propertiesfile are irrelevant.
If all projects share a tag prefix, it is easier to set it in the root project
gradle.propertiesfile instead of passing it constantly via CLI.
The whole format can be:
<major>.<minor>.<patch>[-<stage>.<num>][.<commits number>+<hash>][+<metadata>]
- Format:
<major>.<minor>.<patch> - Example:
1.0.0
- Format:
<major>.<minor>.<patch>[-<stage>.<num>] - Example:
1.0.0-alpha.1
-
Format:
- Clean repository:
<major>.<minor>.<patch>[-<stage>.<num>][.<commits number>+<hash>] - Dirty repository:
<major>.<minor>.<patch>[-<stage>.<num>][.<commits number>+<DIRTY>]
- Clean repository:
-
Examples:
1.0.0.4+26f04841.0.0.4+DIRTY
It is used the
DIRTYsuffix instead of a timestamp in order to avoid issues with any Gradle cache.
- Format:
<major>.<minor>.<patch>-SNAPSHOT - Example:
1.0.0-SNAPSHOT
To change between stages, use the Gradle project property -Psemver.stage=<stage>
There are reserved stages that can be used to create certain versions:
final: It creates a version without a suffix stage, for example,1.0.1.auto: It calculates automatically the next stage based on the previous stage.snapshot: It generate the next snapshot version, for example,1.0.1-SNAPSHOT.
# gradle.properties
semver.tagPrefix=v# Last tag = v1.0.0-alpha.1
./gradlew "-Psemver.stage=alpha" # v1.0.0-alpha.2
./gradlew "-Psemver.stage=beta" # v1.0.0-beta.1
./gradlew "-Psemver.stage=rc" # v1.0.0-rc.1
./gradlew "-Psemver.stage=snapshot" # v1.0.1-SNAPSHOT (uses the next patch version)
./gradlew "-Psemver.stage=final" # v1.0.0
./gradlew "-Psemver.stage=auto" # v1.0.0-alpha.2
# Last tag = v1.0.0
./gradlew "-Psemver.stage=alpha" # v1.0.1-alpha.1
./gradlew "-Psemver.stage=beta" # v1.0.1-beta.1
./gradlew "-Psemver.stage=rc" # v1.0.1-rc.1
./gradlew "-Psemver.stage=snapshot" # v1.0.1-SNAPSHOT (still uses the same patch version)
./gradlew "-Psemver.stage=final" # v1.0.1
./gradlew "-Psemver.stage=auto" # v1.0.1The stage order is based on the Gradle official rules, some samples are:
- If both are non-numeric, the parts are compared alphabetically, in a case-sensitive manner:
1.0.0-ALPHA.1<1.0.0-BETA.1<1.0.0-alpha.1<1.0.0-beta.1. devis considered lower than any non-numeric part:1.0.0-dev.1<1.0.0-ALPHA.1<1.0.0-alpha.1<1.0.0-rc.1.- The strings
rc,snapshot,final,ga,releaseandspare considered higher than any other string part (sorted in this order):1.0.0-zeta.1<1.0.0-rc.1<1.0.0-snapshot<1.0.0-ga.1<1.0.0-release.1<1.0.0-sp.1<1.0.0. - These particular values are NOT case-sensitive, as opposed to regular string parts and do not
depend on the separator used around them:
1.0.0-RC.1==1.0.0-rc.1.
Gradle's docs can be found here
To change between scopes, use the Gradle property -Psemver.scope=<scope>
The scope has to be one of major, minor, patch or auto.
# gradle.properties
semver.tagPrefix=v# Last tag = v1.0.0-alpha.1
./gradlew "-Psemver.scope=major" # v2.0.0
./gradlew "-Psemver.scope=minor" # v1.1.0
./gradlew "-Psemver.scope=patch" # v1.0.1
./gradlew "-Psemver.scope=auto" # v1.0.0-alpha.2 (uses the next num version)
# Last tag = v1.0.0
./gradlew "-Psemver.scope=major" # v2.0.0
./gradlew "-Psemver.scope=minor" # v1.1.0
./gradlew "-Psemver.scope=patch" # v1.0.1
./gradlew "-Psemver.scope=auto" # v1.0.1 (uses the next patch version)# gradle.properties
semver.tagPrefix=v# Last tag = v1.0.0-alpha.1
./gradlew "-Psemver.stage=alpha" "-Psemver.scope=major" # v2.0.0-alpha.1
./gradlew "-Psemver.stage=beta" "-Psemver.scope=major" # v2.0.0-beta.1
./gradlew "-Psemver.stage=rc" "-Psemver.scope=major" # v2.0.0-rc.1
./gradlew "-Psemver.stage=final" "-Psemver.scope=major" # v2.0.0
./gradlew "-Psemver.stage=snapshot" "-Psemver.scope=major" # v2.0.0-SNAPSHOT
./gradlew "-Psemver.stage=auto" "-Psemver.scope=auto" # v1.0.0-alpha.2
# Last tag = v1.0.0-alpha.1
./gradlew "-Psemver.stage=alpha" "-Psemver.scope=minor" # v1.1.0-alpha.1
./gradlew "-Psemver.stage=beta" "-Psemver.scope=minor" # v1.1.0-beta.1
./gradlew "-Psemver.stage=rc" "-Psemver.scope=minor" # v1.1.0-rc.1
./gradlew "-Psemver.stage=final" "-Psemver.scope=minor" # v1.1.0
./gradlew "-Psemver.stage=snapshot" "-Psemver.scope=minor" # v1.1.0-SNAPSHOT
# Last tag = v1.0.0-alpha.1
./gradlew "-Psemver.stage=alpha" "-Psemver.scope=patch" # v1.0.1-alpha.1
./gradlew "-Psemver.stage=beta" "-Psemver.scope=patch" # v1.0.1-beta.1
./gradlew "-Psemver.stage=rc" "-Psemver.scope=patch" # v1.0.1-rc.1
./gradlew "-Psemver.stage=final" "-Psemver.scope=patch" # v1.0.1
./gradlew "-Psemver.stage=snapshot" "-Psemver.scope=patch" # v1.0.1-SNAPSHOT
# Last tag = v1.0.0-alpha.1
./gradlew "-Psemver.stage=alpha" "-Psemver.scope=auto" # v1.0.0-alpha.2
./gradlew "-Psemver.stage=beta" "-Psemver.scope=auto" # v1.0.1-beta.1
./gradlew "-Psemver.stage=rc" "-Psemver.scope=auto" # v1.0.1-rc.1
./gradlew "-Psemver.stage=final" "-Psemver.scope=auto" # v1.0.1
./gradlew "-Psemver.stage=snapshot" "-Psemver.scope=auto" # v1.0.1-SNAPSHOT
# Last tag = v1.0.0
./gradlew "-Psemver.stage=alpha" "-Psemver.scope=major" # v2.0.0-alpha.1
./gradlew "-Psemver.stage=beta" "-Psemver.scope=major" # v2.0.0-beta.1
./gradlew "-Psemver.stage=rc" "-Psemver.scope=major" # v2.0.0-rc.1
./gradlew "-Psemver.stage=final" "-Psemver.scope=major" # v2.0.0
./gradlew "-Psemver.stage=snapshot" "-Psemver.scope=major" # v2.0.0-SNAPSHOT
./gradlew "-Psemver.stage=auto" "-Psemver.scope=auto" # v1.0.1
# Last tag = v1.0.0
./gradlew "-Psemver.stage=alpha" "-Psemver.scope=minor" # v1.1.0-alpha.1
./gradlew "-Psemver.stage=beta" "-Psemver.scope=minor" # v1.1.0-beta.1
./gradlew "-Psemver.stage=rc" "-Psemver.scope=minor" # v1.1.0-rc.1
./gradlew "-Psemver.stage=final" "-Psemver.scope=minor" # v1.1.0
./gradlew "-Psemver.stage=snapshot" "-Psemver.scope=minor" # v1.1.0-SNAPSHOT
# Last tag = v1.0.0
./gradlew "-Psemver.stage=alpha" "-Psemver.scope=patch" # v1.0.1-alpha.1
./gradlew "-Psemver.stage=beta" "-Psemver.scope=patch" # v1.0.1-beta.1
./gradlew "-Psemver.stage=rc" "-Psemver.scope=patch" # v1.0.1-rc.1
./gradlew "-Psemver.stage=final" "-Psemver.scope=patch" # v1.0.1
./gradlew "-Psemver.stage=snapshot" "-Psemver.scope=patch" # v1.0.1-SNAPSHOT
# Last tag = v1.0.0
./gradlew "-Psemver.stage=alpha" "-Psemver.scope=auto" # v1.0.1-alpha.1
./gradlew "-Psemver.stage=beta" "-Psemver.scope=auto" # v1.0.1-beta.1
./gradlew "-Psemver.stage=rc" "-Psemver.scope=auto" # v1.0.1-rc.1
./gradlew "-Psemver.stage=final" "-Psemver.scope=auto" # v1.0.1
./gradlew "-Psemver.stage=snapshot" "-Psemver.scope=auto" # v1.0.1-SNAPSHOTThere are three tasks:
printSemver: Prints the tag in CLI and create a file inbuild/semver/version.txtwhich has two lines; the version without the tag and the version including the tag.createSemverTag. Creates a git tag.pushSemverTag. Creates and pushes a git tag to the remote.
You can combine them with any semver project properties to ensure the correct tag version is
printed, created or pushed.
pushSemverTag can use a specific remote if the Gradle property semver.remote is set. If it is
not set, origin is used if it exists, if not, the first remote by name is used. If there is no
remote, the task fails.
Samples:
./gradlew createSemverTag
./gradlew createSemverTag "-Psemver.stage=alpha"
./gradlew pushSemverTag
./gradlew pushSemverTag "-Psemver.stage=alpha"By default, if the repository status is not clean, the version shows the suffix DIRTY but that can
be avoided by setting the Gradle property semver.checkClean.
For example, if the last tag is 1.0.0, there are 23 commits between that tag and the last commit
and the repo is not clean:
./gradlew "-Psemver.stage=final" "-Psemver.scope=patch"
semver: 1.0.0.23+DIRTY./gradlew "-Psemver.stage=final" "-Psemver.scope=patch" "-Psemver.checkClean=false"
semver: 1.0.1./gradlew "-Psemver.checkClean=false"
semver: 1.0.0.23+1a2cd5b2 # 1a2cd5b2 is the last commit hashCopyright 2024 Javier Segovia Cรณrdoba
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent