README.asciidoc

gradle-gitflow

An opinionated plugin that provides Semantic Versioning for Gradle projects that use Gitflow.

This plugin is heavily inspired by the gradle-git plugin.

Important

It intentionally provides no Gradle tasks and interacts with Git just for inferring the version of the project.

This inferred version is set as the project version of the Gradle project to which it is applied.

Versioning

Version rules

The rules applied when inferring the version are that simple:

• If the current commit is tagged this tag is used as a version — regardless of the current branch

  • this would usually be the normal version (major.minor.patch)

• Otherwise the version contains

  • the normal version (major.minor.patch) extracted from the next reachable tag in the history

    • if the current commit is on a pre-release branch, the normal version is extracted from the name of this branch

  • a pre-release identifier indicating the current branch

  • a pre-release identifier indicating the number of commits since the last tag

  • a build metadata identifier indicating the SHA of the current commit

  • a build metadata identifier indicating if the repository is dirty

Version structure

The inferred versions consist of the following components:

1.2.3-dev.65+sha.9066228.dirty
| | |  |  |   |     |      |
| | |  |  |   |     |      indicates if the repository is dirty
| | |  |  |   |     |
| | |  |  |   |     abbreviated SHA of the current commit
| | |  |  |   |
| | |  |  |   prefix of the SHA
| | |  |  |
| | |  |  # of commits since the last tag
| | |  |
| | |  denotes the current branch
| | |
| | patch version
| |
| minor version
|
major version

Mapping between Gitflow branches and pre-release identifiers

The following table shows the mapping between Gitflow branches and the corresponding pre-release identifiers that indicate these branches.

Note

If you use a Gitflow plugin for Git, gradle-gitflow uses the branch names and prefixes of your Gitflow configuration section in .git/config. If you do not use such a plugin, you will either have to stick to the default names in the table below or add Gitflow configuration sections to .git/config as described in Gitflow plugins for Git.

Gitflow branch	Default name in Gitflow plugins	Pre-release identifier	Notes
production release	master	(empty string)
development	develop	dev
feature	feature/foo	feature.foo
next release / pre-release	release/1.2.3	pre	The normal version (major.minor.patch) is extracted from the branch name
hotfix	hotfix/foo	fix.foo
support	support/foo	support.foo

Note	In case the current head is a detached head the pre-release identifier is detached.

Usage

Include the following in the project on which you want to apply the plugin:

buildscript {
  repositories {
    jcenter()
  }

  dependencies {
    classpath 'com.github.amkay:gradle-gitflow:0.2.0'
  }
}

apply plugin: 'com.github.amkay.gitflow'

Note	The latest build of the current development version can always be obtained from here.

Configuration

The plugin registers an extension object named gitflow that is the entry point to the configuration. It also provides a DSL for keyword-based configuration, but configuration via properties is also possible. The following example shows all configuration options:

gitflow {
  // Use a different Git repository
  repositoryRoot 'foo/bar' // defaults to project.projectDir

  // Pre-release identifiers based on Gitflow branches
  preReleaseIds {
    release 'foo'      // defaults to ''
    develop 'foo'      // defaults to 'dev'
    preRelease 'foo'   // defaults to 'pre'
    detachedHead 'foo' // defaults to 'detached'

    // The following ones are used as prefixes
    feature 'foo' // defaults to 'feature'
    hotfix 'foo'  // defaults to 'fix'
    support 'foo' // defaults to 'support'
  }

  // Build metadata identifiers that are used as static text
  buildMetadataIds {
    sha 'foo'   // Defaults to 'sha'
    dirty 'foo' // Defaults to 'dirty'
  }
}

Gitflow plugins for Git

This plugin supports the following Gitflow plugins for Git:

• git-flow

• git-flow (AVH Edition)

If you do not use one of the mentioned plugins and differ from the default names mentioned in Mapping between Gitflow branches and pre-release identifiers, you will have to manually set the branch names and prefixes of the Gitflow branches and prefixes in .git/config like these plugins would do. This is the only way for gradle-gitflow to pick up this configuration.

The following example shows the default configuration of the above plugins:

[gitflow "branch"]
	master  = master
	develop = develop
[gitflow "prefix"]
	feature    = feature/
	release    = release/
	hotfix     = hotfix/
	support    = support/
	versiontag =

Warning

Keep in mind that most CI servers simply clone your repository after being called by a commit hook when you push your code. Therefore you will have to take care in your CI configuration that .git/config contains the Gitflow configuration sections that gradle-gitflow needs if you do not use the default names mentioned in Mapping between Gitflow branches and pre-release identifiers.

Additional functionality of the version object

The following additional functionality is provided by the version object that this plugin provides. You can have a look at the Groovydoc documentation for further information.

Version type

The type of the inferred version is derived from the current branch and corresponds to the branches mentioned in Mapping between Gitflow branches and pre-release identifiers. This can be used in your buildscripts for distinguishing between development and production builds, e.g. for deploying to staging and production as seen in the following example.

import static com.github.amkay.gradle.gitflow.version.VersionType.*

task deploy << {
  if (version.type == DEVELOP) {
    // Deploy to staging...
  } else if (version.type == RELEASE) {
    // Deploy to production...
  }
}

Tip	For additional version types see the enum VersionType in the Groovydoc documentation.