gradle-jgitver-plugin

gradle plugin to define project version using jgitver.

In order to find the latest version published of gradle-jgitver-plugin, go to the gradle plugin portal.

Usage

see the project build.gradle.kts to see how the project is using itself to manage its own versions.

Find latest version of the plugin: click here

Usage for modern gradle versions (>= 2.1)

plugins {
  id "fr.brouillard.oss.gradle.jgitver" version "0.9.1"
}

Usage for all gradle versions (including < 2.1)

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "gradle.plugin.fr.brouillard.oss.gradle:gradle-jgitver-plugin:0.9.1"
  }
}

apply plugin: 'fr.brouillard.oss.gradle.jgitver'

Documentation

See jgitver for a full understanding of the possibilities and usage.

You can also have a look at the maven equivalent: jgitver-maven-plugin.

Finally have a look at the configuration paragraph to have full control on the plugin.

Tasks

Version

Since 0.2.0 the plugin automatically registers a task version which you can call to print out the calculated version of your project:

$ ./gradlew version
:version
Version: 0.0.2-4

BUILD SUCCESSFUL

Total time: 5.769 secs

Before 0.2.0, in order to know the current version of your project, just print out the version in a task looking like the following:

task version {
    doLast {
        println 'Version: ' + version
    }
}

then just call the task

$ ./gradlew version
:version
Version: 0.0.2-4

BUILD SUCCESSFUL

Total time: 5.769 secs

Configuration

version >= 0.2.0

Starting from 0.2.0 it is possible to configure the plugin inside the build.gradle.

jgitver {
  strategy MAVEN | CONFIGURABLE | PATTERN
  mavenLike true/false          (deprecated, use strategy instead)
  policy MAX | LATEST | NEAREST
  autoIncrementPatch true/false
  useDistance true/false
  useDirty true/false
  useSnapshot true/false
  failIfDirty true/false
  useGitCommitTimestamp true/false
  useGitCommitID true/false
  gitCommitIDLength integer
  maxDepth integer              ( >= 0.7.0) 
  nonQualifierBranches string   (comma separated list of branches)
  versionPattern string         (only for PATTERN strategy, >= 0.6.0)
  tagVersionPattern string      (only for PATTERN strategy >= 0.6.0)
  policy {                         repeatable closure
    pattern string              (regexp with capturing group)
    transformations array       (array of string)
  }
  distanceCalculatorKind FIRST_PARENT | LOG | DEPTH 
}

If you do not provide such a configuration (or fill only partial configuration) the following defaults will be used

• strategy: CONFIGURABLE
• mavenLike: false
• policy: MAX
• autoIncrementPatch: true
• useDistance: true
• useDirty: false
• useSnapshot: false
• failIfDirty: false
• useGitCommitTimestamp: false
• useGitCommitID: false
• gitCommitIDLength: 8
• maxDepth: Integer.MAX_VALUE
• nonQualifierBranches: 'master'
• versionPattern: no default value
• tagVersionPattern: no default value
• regexVersionTag: 'Java regexp pattern'
  • if non set or null then jgitver default applies
  • the pattern must be a regular Java Pattern string with one matching group
• distanceCalculatorKind: FIRST_PARENT

version < 0.2.0

Before 0.2.0 no configuration was possible.
The plugin used jgitver with the following settings:

• mavenLike: false
• autoIncrementPatch: true
• nonQualifierBranches: 'master'
• useDistance: true
• useGitCommitId: false

Configuration examples

provide specific branch policies

Given the following configuration

jgitver {
    policy {
		pattern = 'feature_(.*)' 
		transformations = ['REMOVE_UNEXPECTED_CHARS', 'UPPERCASE']
	}
    policy {
		pattern = '(master)' 
		transformations = ['IGNORE']
	}
}

when on branch feature_login-page, 3 commits after tag 1.0.0 then version resolution will be 1.0.1-3-LOGINPAGE

$ gradlew version

> Task :version
Version: 1.0.1-3-LOGINPAGE

Metadatas

Since 0.3.0, jgitver Metadatas are exposed via gradle extension properties using the Metadata name in lower case.

For example, one could enhance it's jar Manifest with the git commit id using:

apply plugin: 'java'
apply plugin: 'fr.brouillard.oss.gradle.jgitver'

jar {
    doFirst {
        manifest {
            manifest.attributes 'X-GIT-SHA1': "$project.ext.git_sha1_full"
        }
    }
}

Building on detached HEAD

When working on a detached HEAD, as often on CI environments behind a SCM webhook, no branch information exists anymore from git. Since 0.4.1 it now possible to provide externally the branch information via a system property or an environment variable.

• all operating systems/shells: gradlew version -Djgitver.branch=mybranch
• bash only (zsh?) one line: JGITVER_BRANCH=mybranch && gradlew version
• *nix shell:
  • export JGITVER_BRANCH=mybranch
  • gradlew version
• windows:
  • SET JGITVER_BRANCH=mybranch
  • gradlew version

Local build & sample test project

• $ ./gradlew install version will install the current version inside the local maven repository and will print the published version
• minimal test project build.gradle file

  buildscript {
    repositories {
    mavenLocal()
    }
    dependencies {
      classpath "fr.brouillard.oss.gradle:gradle-jgitver-plugin:0.3.2"
    }
  }
  apply plugin: 'fr.brouillard.oss.gradle.jgitver'
  

• test project build.gradle file with Maven like versioning

  buildscript {
    repositories {
    mavenLocal()
    }
    dependencies {
      classpath "fr.brouillard.oss.gradle:gradle-jgitver-plugin:0.3.2"
    }
  }
  apply plugin: 'fr.brouillard.oss.gradle.jgitver'
  
  jgitver {
    mavenLike true
  }
  

Integration tests

Some integration tests are available to make some manual trials/verifications of the plugin.

./gradlew install version
cd src/test/integration/test
./build.sh CONTEXT JGITVER_GRADLE_VERSION EXPECTED_COMPUTED_VERSION
# example ./build.sh tag-regexp 0.5.1-2 2.0.1-1

Linux environment for windows users

The easiest way to get started from Windows is to launch a docker container:

• docker -v run --rm -it -v %CD%:/project -w /project adoptopenjdk/openjdk8 /bin/bash
• $ apt-get update && apt-get install -y git

Release

• git tag -a -s -m "release X.Y.Z, additionnal reason" X.Y.Z: tag the current HEAD with the given tag name. The tag is signed by the author of the release. Adapt with gpg key of maintainer.
  • Matthieu Brouillard command: git tag -a -s -u 2AB5F258 -m "release X.Y.Z, additionnal reason" X.Y.Z
  • Matthieu Brouillard public key
• ./gradlew publishPlugins
• git push --follow-tags origin master