Skip to content

Latest commit

 

History

History
189 lines (146 loc) · 6.47 KB

README.md

File metadata and controls

189 lines (146 loc) · 6.47 KB
Raw

👻 semver-git-plugin

Version your gradle projects with git tags and semantic versioning.

GitHub version License Build Status codecov

Apply the plugin

Gradle 2.1 and higher

plugins {
    id("io.wusa.semver-git-plugin").version("2.3.7")
}

Gradle 1.x and 2.0

buildscript {
   repositories {
      maven {
         url "https://plugins.gradle.org/m2/"
       }
   }
   dependencies {
      classpath 'io.wusa:semver-git-plugin:2.3.7'
   }
}

apply plugin: 'io.wusa.semver-git-plugin'

Configure the plugin

semver {
    snapshotSuffix = "SNAPSHOT" // (default) appended if the commit is without a release tag
    dirtyMarker = "dirty" // (default) appended if the are uncommitted changes
    initialVersion = "0.1.0" // (default) initial version in semantic versioning
    tagPrefix = "" // (default) each project can have its own tags identified by a unique prefix.
    tagtype = TagType.Annotated // (default) options are Annotated or Lightweight
    branches { // list of branch configurations
        branch {
            regex = ".+" // regex for the branch you want to configure, put this one last
            incrementer = "NO_VERSION_INCREMENTER" // (default) version incrementer
            formatter = { "${semver.info.version.major}.${semver.info.version.minor}.${semver.info.version.patch}+build.${semver.info.count}.sha.${semver.info.shortCommit}" } // (default) version formatting closure
        }
    }
}

Use with a Gradle multi-module project

For projects which take advantage of Gradle's multi-module projects, it is possible to specify different tags for each module.

The tags for each module must be distinguished with an unambiguous prefix. For example, if you have three modules foo, bar, and blega, you may consider using the module name as the prefix. This prefix is configured in the semver configuration block:

semver {
  tagPrefix = "foo-"
}

Given the above configuration, the tags for the "foo" module must all begin with "foo-"; e.g., "foo-3.2.6", etc... Note that besides the prefix, the rules for the tag names must still follow all the same semver rules as apply in any other case.

Incrementer

Incrementer Description
NO_VERSION_INCREMENTER Doesn't increment the version at all.
PATCH_INCREMENTER Increments the patch version by one.
MINOR_INCREMENTER Increments the minor version by one.
MAJOR_INCREMENTER Increments the major version by one.
CONVENTIONAL_COMMITS_INCREMENTER Increments the version according to conventional commits.

Release

The versions have to be stored as annotated or lightweight (depending on the configured tag type) git tags in the format of semantic versioning.

To create a new annotated release tag:

git tag -a 1.0.0-alpha.1 -m "new alpha release of version 1.0.0"
git push --tags

To create a new lightweight release tag:

git tag -a 1.0.0-alpha.1
git push --tags

Following commits without a release tag will have the snapshotSuffix (default SNAPSHOT) appended and the version number bumped according to incrementer (default minor) strategy, e.g., 1.1.0-alpha.1-SNAPSHOT.

Version usage

Then you can access the version of your project via semver.info.

Examples:

allprojects {
    version = semver.info
}
project.version = semver.info

Version information

semver.info

Access the following information via semver.info.* e.g., semver.info.tag.

Property Description Git: master Git: feature/ghosty
info.branch.group Group of the branch master feature
info.branch.name Name of the branch master feature/ghosty
info.branch.id Tokenized branch name master feature-ghosty
info.commit Full sha1 commit hash 4ecabe2e8646fd0b577dcda83e5c23447e230496 4ecabe2e8646fd0b577dcda83e5c23447e230496
info.shortCommit Short sha1 commit has d2459d d2459d
info.tag Current tag If any name of the tag else none If any name of the tag else none
info.lastTag Last tag If any name of the tag else none If any name of the tag else none
info.dirty Current state of the working copy true if the working copy contains uncommitted files true if the working copy contains uncommitted files
info Formatted version 0.1.0 0.1.0
info.version.major Major version of 2.0.0-rc.1+build.123 2 2
info.version.minor Minor version of 2.0.0-rc.1+build.123 0 0
info.version.patch Patch version of 2.0.0-rc.1+build.123 0 0
info.version.build Build number of 2.0.0-rc.1+build.123 build.123 build.123
info.version.prerelease Pre release of 2.0.0-rc.1+build.123 rc.1 rc.1

Display version

The semver.info is based on the current or last tag (depending on the specified tag type).

  • If the current commit has an tag this tag will be the version.
  • If the current commit has no tag the version takes the last tag and builds the new version based on:
    • The ordering of the branch configuration is important for the matching.
  • If no tag exists the initial commit will be version 0.1.0 as recommended by Semantic Versioning 2.0.0. The following commits will be build based on this version until a tag is created.

Tasks

The semver plugin offers two tasks.

showVersion

Displays the version information:

> Task :showVersion
Version: 0.0.1

showInfo

Displays the full info:

> Task :showInfo
Branch name: feature/test
Branch group: feature
Branch id: feature-test
Commit: fd132d87d51cee610c5b273050625850e1d62a3b
Short commit: fd132d8
Tag: none
Last tag: 0.0.1
Dirty: false
Version: 0.1.0-SNAPSHOT
Version major: 0
Version minor: 1
Version patch: 0
Version pre release: none
Version build: none

License

The MIT License (MIT)