jgitver: git versioning library

The goal of jgitver is to provide a standardized way, via a library, to calculate a project semver compatible version from a git repository and its content: tags, branches, HEAD, ...

With this automation & standardization it is then possible to:

• have clear, controlled & respected naming rules for project versions
• setup clean Continuous Integration (version per branch, ...)
• keep your project history clean, no more polluting commits to update any project descriptor

Project statuses

• 
• 
• 
• 
• 
• 
• 

How it works

jgitver uses annotated tags, lightweight tags, branches names & commits to deduce/calculate the version of a particular git commit.
From a given commit, a little bit like git describe command, jgitver walks through the commit tree to retrieve information (including tags, distance, ...) on ancestor commit(s). From there, depending on the configuration, a version will be deducted/calculated.

Simplicity & power

jgitver comes with default modes that follow best practices & conventions making it a no brainer to use with good defaults but you can configure it to work as you would like to.

versions, identifier & qualifiers

When computing versions, jgitver focuses on providing semver compatible versions.

• version: as defined by semver, a serie of X.Y.Z where X, Y & Z are non-negative integers
• identifier: a textual information following the version, build from alphanumeric characters & hyphen
• qualifiers: qualifiers are textual information that can be combined to build a semver identifier

Quick examples

Before going into deep explanations & documentation let's first show what you will have when using jgitver on your git projects.

Using default configuration with increment

Using default maven like configuration

Usage

via build plugins

Most of the time you will want to use jgitver via one of its extensions/plugins:

• jgitver maven plugin, which can be used as a core maven extension by creating a file YOUR_PROJECT/.mvn/extensions.xml:

  <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.5.1</version>
    </extension>
  </extensions>
  

  find latest version on & read jgitver maven plugin homepage for further configuration with maven.

• jgitver gradle plugin which can be used using plugins DSL syntax:

  plugins {
    id "fr.brouillard.oss.gradle.jgitver" version "X.Y.Z"
  }
  

  find the latest version in gradle plugin portal

Using the CLI

Starting with 0.10.0 we provide an executable jar able to run jgitver from the cli.

Usage: java -jar jgitver-executable.jar [-hV] [--autoIncrementPatch]
                                        [--useDirty] [--useDistance]
                                        [--useGitCommitId]
                                        [--useGitCommitTimestamp]
                                        [--useLongFormat] [--dir=<directory>]
                                        [--gitCommitIdLength=<gitCommitIdLength>
                                        ] [--metas=<metadatas>]
                                        [--nonQualifierBranches=<nonQualifierBra
                                        nches>] [--pattern=<pattern>]
                                        [--policy=<policy>]
                                        [--strategy=<strategy>]
                                        [--branchPolicyPattern=<branchPolicyPat
                                        tern> [--branchPolicyTransformations=<b
                                        ranchPolicyTransformations>[,<branchPol
                                        icyTransformations...]...]...
                                        [--tagVersionPattern=<tagVersionPattern
                                        >]
                                        [--versionPattern=<VersionPattern>]
      --autoIncrementPatch   activate auto increment patch functionality
      -fc, --forceComputation
                             activate forceComputation flag
      --dir, --directory=<directory>
                             root directory for git project
      --gitCommitIdLength=<gitCommitIdLength>
                             length of the git commit id if used
      --metas, --metadatas=<metadatas>
                             metadatas to show, separated by ','
      --nonQualifierBranches=<nonQualifierBranches>
                             list of fixed name for non qualifier branches
      --pattern=<pattern>    pattern to identify base tags as versionable ones
      --policy=<policy>      lookup policy to use to find the base tag to use
      --strategy=<strategy>  defines the strategy to use
      --useDirty             activate dirty flag
      --useDistance          activate distance qualifier
      --useGitCommitId       add git commit id as qualifier
      --useGitCommitTimestamp
                             add git commit timestamp as qualifier
      --useLongFormat        activate long format usage
      --branchPolicyPattern=<branchPolicyPattern>
                             regex to match a branch name
      --branchPolicyTransformations=<branchPolicyTransformations>[,
          <branchPolicyTransformations>...]
                             transformations to apply to the
                                 branchPolicyPattern match
      --tagVersionPattern=<tagVersionPattern>
                             set the pattern for when on annotated tag
                                 (PATTERN strategy)
      --versionPattern=<versionPattern>
                             set versionPattern (PATTERN strategy)
                                     
  -h, --help                 display usage
  -V, --version              display version info

You can find the latest executable file on maven central.

--tagVersionPattern and --versionPattern were added in 0.12.0 and only apply when the PATTERN strategy is active.

--branchPolicyPattern and --branchPolicyTransformations were also added in 0.12.0. They are grouped arguments and pair up with each other to behave like the policy settings on the Maven and Gradle plugins.

As a java library

But of course, jgitver is a java library published on maven central and can be used as such.

package fr.brouillard.oss.jgitver;

import java.io.File;

public class UsageExample {
    /**
     * Display the calculated version of the working directory, using jgitver in mode 'maven like'.
     */
    public static void main(String[] args) throws Exception {
        File workDir = new File(System.getProperty("user.dir"));
        try (GitVersionCalculator jgitver = GitVersionCalculator.location(workDir).setMavenLike(true)) {
            System.out.println(jgitver.getVersion());
        }
    }
}

Concepts

Annotated tags

When the HEAD is on a git commit which contains an annotated tag that matches a version definition, this annotated tag is used to extract the version.

Lightweight tags

Lightweight tags are used by jgitver to better control the resulting version calculation (for example jump from 1.0.X scheme to 2.0.X starting from commit ABCDEF).

If you do not know the difference between lightweight & annotated tags, please refer to git documentation ; here is an extract of git tag man page.

Annotated tags are meant for release while lightweight tags are meant for private or temporary object labels. For this reason, some git commands for naming objects (like git describe) w