jgitver logo

jgitver consists of a set of library and plugins allowing to automatically compute project versions based on:

  • git history

  • git tags (annotated & lightweight)

  • git branches

  • configuration (predefined or explicit)

1. About

because we believe in some high level principles like "DRY (Don’t Repeat Yourself"), "clean git history" we created jgitver to allow automatic computation of project versions without unnecessary steps or edits of files.

1.1. Goal

without changing pom.xml files or build.gradle, simply with git commit, git tag & git branch commands, your project descriptors versions are automatically computed when you launch a build command like mvn package or gradle build

  • pom.xml version computations using defaults in maven mode:

jgitver maven defaults
Figure 1. jgitver using default maven configuration
  • build.gradle version computations using defaults in gradle mode:

jgitver gradle defaults
Figure 2. jgitver using default gradle configuration

jgitver is highly configurable. You can define & infuence the way the version is computed. See the User Documentation for more details.

1.2. Clean Git history

because project version are computed automatically, there is no need anymore to pollute the project git history with some infamous unnecessary commits.

Yes maven:release we’re looking at you !

On some projects, some 1/3 of commits are related to maven:release and the pom changes to adapt the version tag inside the pom.xml

maven release on maven war plugin
Figure 3. Isn’t that git history pollution?

Using jgitver a release process becomes really simple: tag & deploy

maven release with jgitver is reduced to the following
git tag -a X.Y.Z
mvn deploy

2. Getting Started

2.1. Maven usage

For maven world, jgitver is provided as a maven core extension ; as such it needs to be referenced inside a file YOUR_PROJECT/.mvn/extensions.xml. If you do not have already an extension file, create one using any below technique.

2.1.1. Automatic creation of .mvn/extensions.xml

In order to automatically create .mvn/extensions.xml file with latest jgitver version

  • using curl:

sh -c "$(curl -fsSL https://git.io/fA6sj)"
  • using wget:

sh -c "$(wget -q https://git.io/fA6sj -O -)"

2.1.2. Manual edition of .mvn/extensions.xml

  • Create a directory .mvn under the root directory of your project.

  • Create file .mvn/extensions.xml

  • Put the following content to .mvn/extensions.xml (adapt to latest version).

<extensions xmlns="http://maven.apache.org/EXTENSIONS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/EXTENSIONS/1.0.0 http://maven.apache.org/xsd/core-extensions-1.0.0.xsd">
  <extension>
    <groupId>fr.brouillard.oss</groupId>
    <artifactId>jgitver-maven-plugin</artifactId>
    <version>1.4.3</version>
  </extension>
</extensions>

2.1.3. let jgitver operate

Once you have created the file, your project versioning is now handled by jgitver. Just launch mvn validate to see jgitver in action on your project ; now you can see it computing your project version.

Maven launch on jgitver project itself
$ mvn validate
[INFO] no suitable configuration file found, using defaults
[INFO] Scanning for projects...
[INFO] Using jgitver-maven-plugin [1.3.0] (sha1: ef8eec9f820d662e63a84f1210c377183e450cbd)
[INFO] jgitver-maven-plugin is about to change project(s) version(s)
[INFO]     fr.brouillard.oss::jgitver::0 -> 0.7.0-SNAPSHOT

2.1.4. Online demo

If you want to quickly evaluate jgitver while being guided in the different steps, please follow the jgitver interactive guide on the katakoda platform.

jgitver katakoda getting started on maven

2.2. Gradle usage

Using jgitver with gradle is as simple as adding it as a plugin

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

Congrats, your project now uses jgitver !

$ gradle version

> Task :version
Version: 1.1.0-1

BUILD SUCCESSFUL in 1s

gradle version < 2.1

Above declaration only works for gradle >= 2.1, another way of declaring the plugin, working for all gradle versions including the ones < 2.1

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

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

2.2.1. Online demo

If you want to quickly evaluate jgitver while being guided in the different steps, please follow the jgitver interactive guide on the katakoda platform.

jgitver katakoda getting started on gradle

3. User documentation

this section is WIP

see the projects section to access existing projects README.

3.1. Modes

jgitver provides different ways of computing version called 'modes' or 'strategies'. Each mode comes with some behavior, defaults and configuration capabilities.

3.1.1. maven mode

The maven mode is built to reflect maven way of versioning: SNAPSHOTs and RELEASEs

In this mode (which is the default mode of the jgitver maven plugin), jgitver will:

  • on a DETACHED HEAD having an annotated tag, use the tag name without further computation : mean to release

  • add SNAPSHOT qualifier to the calculated version each time it is not in the previous state : everything is a SNAPSHOT except a release

  • increase the patch version except if it comes from a lightweight tag : mean to start a new version pattern numbering

  • use annotated tags before lightweight ones when on a DETACHED HEAD : reproducible builds for release

  • use lightweight tags before annotated ones when on a normal branch (master or any other branch) : start 'next' version after release

  • add a branch qualifier on purpose : avoid version collision for feature branches

3.1.2. default mode

The default mode is built to reflect a standard way of versioning, each commit being uniquely identified.

In this mode (which is the default mode of the jgitver gradle plugin), jgitver will:

  • on a DETACHED HEAD having an annotated tag, use the tag name without further computation

  • use annotated tags before lightweight ones when on a DETACHED HEAD

  • use lightweight tags before annotated ones when on a normal branch (master or any other branch)

    • exception is when HEAD is on current branch, lightweight tags have precedence only when the repository is dirty

  • add a branch qualifier on purpose

3.1.3. pattern mode

This mode allows some freedom to the project owner. As a project maintainer you define/configure your own pattern of versioning.

The pattern mode is new in jgitver-0.7.0 and is to be considered as beta feature.

In this mode, jgitver computes some metadatas that can be used in a pattern definition, provided by configuration, to compute the final version.

this section needs enhancements. Partial information can be found in jgitver#33.

3.2. Maven configuration

this section is WIP

see the jgitver-maven-plugin project README until the doc is enhanced.

3.3. Gradle configuration

this section is WIP

see the gradle-jgitver-plugin project README until the doc is enhanced.

3.4. IDEs usage

By providing dynamic versioning, jgitver is not currently the best friend of IDEs.

But on the other hand your IDE is probably not your build tool ; so it is not a problem if it does understand all of your build pipeline.

Please refer to the instructions of your preferred IDE and if you need projects dependencies within the IDE then look at the latest paragraph.

3.4.1. Eclipse

Having jgitver setup on your project does not hurt Eclipse at all.

Just import your project as you would do normally. Eclipse will import it using the content of your pom.xml file, it will not evaluate version using jgitver.

3.4.2. Intellij IDEA

Unfortunately, Intellij IDEA still does not work out of the box when jgitver is there. The problem has been reported to Intellij under the following issue IDEA-187928.

To workaround Intellij failure, you have to deactivate jgitver for the import step. For maven projects for example, open the settings CTRL+ALT+S and modify imports settings by adding -Djgitver.skip=true as in the below image.

intellij skip jgitver

3.4.3. Netbeans

Exactly like Eclipse does, Netbeans just use the content of the pom.xml while importing your project. Just import your project as you would do normally.

3.4.4. Project dependencies within IDEs

If you want to open several projects within your IDE and make project references between those projects then having projects which version is dynamically changing is not the best way to help your IDE keeping the references between the projects.

Especially if your are not using maven like SNAPSHOT but unique version for each of your commits then it is better to bypass the dynamic nature of jgitver.

this section is WIP

4. Developer documentation

4.1. Projects

jgitver is composed by:

  • jgitver library: a java library using git that computes a git repository version based on a given configuration

  • jgitver maven plugin: a maven core extension allowing to compute POM versions without any effort or pom.xml modification

  • jgitver gradle plugin: a gradle plugin allowing to compute gradle project version

As it is always good to eat your own food, all the above projects self-use either the jgitver maven plugin or gradle one ; thus you can look at them as examples.

4.2. Contribution

this section is WIP

Any kind of contribution is highly appreciated and welcome.

You can help the project in many ways:

  • leverage it’s usage in your company

  • create a blog, tweet, post on social media ; make some awareness of the project

  • star the projects on github

  • ask & answer questions on the gitter chat room

  • report issues in each projects issues page (library, maven, gradle)

  • participate in documentation enhancement (VERY important)

  • new feature or bug fixing via a PR on each project

  • support the project:

4.3. Who is using jgitver

If you want your company/project to be named here you can either:

  • send me a Twitter URL

  • push me an email Matthieu%20Brouillard blue

  • open an issue

  • create a PR

jgitver is already in use in:

4.4. Support

4.4.1. Community Support

  • for a question about the usage of jgitver or any of it’s plugin, please use the jgitver room.

  • in case of bug please open an issue:

  • to contribute to this documentation, please read the README, open a pull request with your change

  • due to history, the maven plugin had also a wiki. There is a continuous effort to migrate the wiki pages into the official documentation project.

4.4.2. Professional support

For anything outside of the community support please contact me email Matthieu%20Brouillard blue Twitter URL