{"id":13610032,"url":"https://github.com/ethauvin/semver-gradle","last_synced_at":"2025-05-05T02:53:34.312Z","repository":{"id":146413843,"uuid":"139215299","full_name":"ethauvin/semver-gradle","owner":"ethauvin","description":"Semantic Version Plugin for Gradle","archived":false,"fork":false,"pushed_at":"2025-04-26T05:27:11.000Z","size":798,"stargazers_count":23,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-26T06:25:19.836Z","etag":null,"topics":["auto-increment","gradle","java","kotlin","plugin","semantic","semver","version","versioning"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethauvin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.TXT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-30T03:14:34.000Z","updated_at":"2024-06-25T22:15:15.000Z","dependencies_parsed_at":"2024-01-16T23:30:44.686Z","dependency_job_id":"6090725e-0473-4d58-9599-7a01ee6cde27","html_url":"https://github.com/ethauvin/semver-gradle","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethauvin%2Fsemver-gradle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethauvin%2Fsemver-gradle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethauvin%2Fsemver-gradle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethauvin%2Fsemver-gradle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethauvin","download_url":"https://codeload.github.com/ethauvin/semver-gradle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252429952,"owners_count":21746571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auto-increment","gradle","java","kotlin","plugin","semantic","semver","version","versioning"],"created_at":"2024-08-01T19:01:40.529Z","updated_at":"2025-05-05T02:53:34.293Z","avatar_url":"https://github.com/ethauvin.png","language":"Kotlin","funding_links":[],"categories":["Kotlin"],"sub_categories":[],"readme":"[![License (3-Clause BSD)](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg?style=flat-square)](http://opensource.org/licenses/BSD-3-Clause) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ethauvin_semver-gradle\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=ethauvin_semver-gradle) [![Build Status](https://travis-ci.com/ethauvin/semver-gradle.svg?branch=master)](https://travis-ci.com/ethauvin/semver-gradle) [![CircleCI](https://circleci.com/gh/ethauvin/semver-gradle/tree/master.svg?style=shield)](https://circleci.com/gh/ethauvin/semver-gradle/tree/master) [![Gradle](https://img.shields.io/maven-metadata/v/https/plugins.gradle.org/m2/net/thauvin/erik/gradle/semver/maven-metadata.xml.svg?label=gradle\u0026color=blue)](https://plugins.gradle.org/plugin/net.thauvin.erik.gradle.semver)\n\n# Semantic Version Plugin for Gradle\n\nA [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.\n\nThe plugin can be used in conjunction with the [__Semantic Version Annotation Processor__](https://github.com/ethauvin/semver).\n\n## Using the plugin\n\nThe 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)\n\n## Version Properties File\n\nBy default, a [properties](https://docs.oracle.com/javase/tutorial/essential/environment/properties.html) file named `version.properties` will be created when Gradle is run:\n\n```ini\n#version.properties\nversion.major=1\nversion.minor=0\nversion.patch=0\nversion.prerelease=\nversion.buildmeta=\nversion.semver=1.0.0\n```\n\nTo change the version of your project, remove the version from `build.gradle` and simply edit the version properties file to match your version number.\n\n- __Examples__: [Java](https://github.com/ethauvin/semver-gradle/tree/master/examples/java), [Kotlin](https://github.com/ethauvin/semver-gradle/tree/master/examples/kotlin)\n\nIf 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.\n\n## Increment Version Tasks\n\n### incrementMajor, incrementMinor and incrementPatch\n\nThe `incrementMajor`, `incrementMinor` and `incrementPatch` tasks are available to automatically increment their respective and reset lower counterpart version numbers.\n\n- `incrementMajor` will increment the `major` and set the `minor` and `patch` versions to `0`.\n- `incrementMinor` will increment the `minor` and set the path version to `0`.\n\n#### Examples\n\n```sh\n./gradlew incrementPatch ...\n```\n\nor in your `gradle.build` file:\n\n```gradle\nsomeTask {\n    dependsOn(incrementPatch)\n    ...\n}\n```\n\n- __Examples__: [Java](https://github.com/ethauvin/semver-gradle/tree/master/examples/java), [Kotlin](https://github.com/ethauvin/semver-gradle/tree/master/examples/kotlin)\n\n### incrementBuildMeta\n\nThe `incrementBuildMeta` task is available to set the build metadata version to a custom calculated value.\n\n#### Examples:\n\nTo set the build metadata to a custom formatted date:\n\n```gradle\nincrementBuildMeta {\n    doFirst {\n        buildMeta = new Date().format(\"yyyyMMddHHmmss\")\n    }\n}\n```\n\n```bash\n./gradlew incrementBuildMeta\n\n...\n\n\u003e Task :incrementBuildMeta\nVersion: 1.0.16-beta+20180713143416\n```\n\nOr to set the build metadata to a custom formatted number with increment:\n\n\n```gradle\nincrementBuildMeta {\n    doFirst {\n        buildMeta = sprintf(\"%03d\", (buildMeta as Integer) + 1)\n    }\n}\n```\n\n```bash\n./gradlew incrementBuildMeta\n\n...\n\n\u003e Task :incrementBuildMeta\nVersion: 1.0.16-beta+002\n```\n\n- __Examples__: [Java](https://github.com/ethauvin/semver-gradle/tree/master/examples/java), [Kotlin](https://github.com/ethauvin/semver-gradle/tree/master/examples/kotlin)\n\n## Command Line\n\nThe `major`, `minor`, `patch`, `prerelease` and `buildmeta` versions can also be set via the command line:\n\n```bash\n./gradlew -Dversion.prerelease=beta -Dversion.buildmeta= ...\n```\n\n```ini\n#version.properties\nversion.major=1\nversion.minor=0\nversion.patch=0\nversion.prerelease=beta\nversion.buildmeta=\nversion.semver=1.0.0-beta\n```\n\nThe full semantic version can also be specified via the `semver` property:\n\n```sh\n./gradlew -Dversion.semver=1.0.0-beta ...\n```\n\nIf a version cannot be parsed your build will **fail**.\n\n## Configuration\n\n### Version File Properties\n\nThe following default properties are recognized:\n\nProperty                    | Description                 | Default\n:-------------------------- |:----------------------------|:---\n`version.major`             | The major version.          | `1`\n`version.minor`             | The minor version.          | `0`\n`version.patch`             | The patch version.          | `0`\n`version.prerelease`        | The pre-release version     |\n`version.prerelease.prefix` | The pre-release prefix      | `-`\n`version.buildmeta`         | The build metatdata version |\n`version.buildmeta.prefix`  | The build metadata prefix   | `+`\n`version.separator`         | The version separator.      | `.`\n\nThe version number is built as follows:\n\n\n`version.major` `version.separator` `version.minor` `version.separator` `version.patch` `[` `version.prerelease.prefix` `version.prerelease` `]` `[` `version.prerelease.prefix` `version.buildmeta` `]`\n\nFor reference, it is automatically included in the `version.semver` property.\n\nfor example:\n\n```ini\n#version.properties\nversion.major=1\nversion.minor=0\nversion.patch=0\nversion.prerelease=beta\nversion.buildmeta=exp.sha.5114f85\nversion.semver=1.0.0-beta+exp.sha.5114f85\n```\n\n`project.version` will be `1.0.0-beta+exp.sha.5114f85` in Gradle.\n\n\n- __Examples__: [Java](https://github.com/ethauvin/semver-gradle/tree/master/examples/java), [Kotlin](https://github.com/ethauvin/semver-gradle/tree/master/examples/kotlin)\n\n### Semver\n\nIn 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.\n\nBut, for example, if you wanted to save the version properties in a different file:\n\n```gradle\nsemver {\n    properties = \"my.version\" // read and save properties in \"my.version\"\n}\n```\n\nor using different property keys for the version data:\n\n```gradle\nsemver {\n    keysPrefix = \"\" // no prefix\n    semverKey = \"version\"\n    majorKey = \"maj\"\n    minorKey = \"min\"\n    patchKey = \"build\"\n    preReleaseKey = \"rel\"\n    buildMetaKey = \"meta\"\n}\n```\nwhich would match the data in `my.version`:\n\n```ini\n#my.version\nmaj=1\nmin=0\nbuild=0\nrel=beta\nmeta=\nversion=1.0.0-beta\n```\n\nThe following `semver` properties are available:\n\nProperty              | Description                             | Default\n:---------------------|:----------------------------------------|:---------------------------\n`properties`          | The properties file.                    | `version.properties`\n`semverKey`           | The semver property key.                | `version.semver`\n`majorKey`            | The major property key.                 | `version.major`\n`minorKey`            | The minor property key.                 | `version.minor`\n`patchKey`            | The patch property key.                 | `version.patch`\n`preReleaseKey`       | The pre-release property key.           | `version.prerelease`\n`preReleasePrefixKey` | The build pre-release prefix key.       | `version.prerelease.prefix`\n`buildMetaKey`        | The build metadata property key.        | `version.buildmeta`\n`buildMetaPrefixKey`  | The build metadata prefix property key. | `version.buildmeta.prefix`\n`separatorKey`        | The separator property key.             | `version.separator`\n`keysPrefix`          | The prefix for all property keys.       | `version.`\n\nIn order to quickly support multiple projects. The `keysPrefix` property is available to set all properties keys prefixes at once:\n\n```gradle\nsemver {\n    properties = \"test.properties\"\n    keysPrefix = \"test.\"\n}\n```\n\n```ini\n#test.properties\ntest.major=1\ntest.minor=0\ntest.patch=0\ntest.prerelease=\ntest.buildmeta=\ntest.semver=1.0.0\n```\n\n- __Examples__: [Java](https://github.com/ethauvin/semver-gradle/tree/master/examples/java), [Kotlin](https://github.com/ethauvin/semver-gradle/tree/master/examples/kotlin)\n\n### Semver Extension Properties\n\nThe values stored in the version properties file can individually be accessed using the `semver` extension, for example:\n\n```gradle\n    fooTask {\n        doFirst {\n            println \"Build: $semver.buildMeta\"\n        }\n    }\n```\n\nThe semver extension properties are:\n\nProperty                  | Description\n:-------------------------|:----------------------------\n`semver.semver`           | The full semantic version.\n`semver.version`          | Same as `semver.semver`.\n`semver.major`            | The major version.\n`semver.minor`            | The minor version.\n`semver.patch`            | The patch version.\n`semver.preRelease`       | The pre-release version\n`semver.preReleasePrefix` | The pre-release prefix\n`semver.buildMeta`        | The build metatdata version\n`semver.buildMetaPrefix`  | The build metadata prefix\n`semver.separator`        | The version separator.\n\n## Version is \"unspecified\"\n\nThis is a common problem stemming from the configuration and build phases in Gradle.\n\nIt is always preferable to access to version during the execution stage, in a `doFirst` or `doLast` closure within your tasks:\n\n```gradle\ntask foo() {\n    doFirst {\n        println project.version\n    }\n}\n```\n\nor if absolutely necessary, at the end of the configuration stage in a `project.afterEvaluate` block:\n\n```gradle\nfoo {\n    project.afterEvaluate {\n        println project.version\n    }\n}\n```\n\n## Source Code Generation\n\nIf 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).\n\nThere 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethauvin%2Fsemver-gradle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethauvin%2Fsemver-gradle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethauvin%2Fsemver-gradle/lists"}