jgitver: git versioning library Discuss

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:

Project statuses

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.

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

Default configuration

Using default maven like configuration

Default maven like

Usage

via build plugins

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

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
      --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) will ignore lightweight tags by default.

In contrary to annotated tags, Lightweight tags are considered by jgitver as ├Čndicators and will be used as a basis for other computation/calculations depending on the configuration:

default version

When no suitable tag can be found in the commit history, then jgitver will consider that a virtual lightweight tag was found on first commit with a version 0.0.0.

Configuration, modes & strategies

Maven strategy

In this mode (which is the default mode of the jgitver maven plugin) activated by a call to GitVersionCalculator#setMavenLike(true), jgitver will:

Parameters affecting this mode:

Default strategy

In this mode, which is the default one, jgitver will:

Then depending on the configuration it will also:

Versions naming & extraction

jgitver uses a pattern recognition in order to filter the tags it uses for any version computation.

The pattern used is the following (interpreted as java.util.regex.Pattern): `v?([0-9]+(?:.[0-9]+){0,2}(?:-[a-zA-Z0-9-_]+)?)``

For non regex experts basically it identifies:

Metadatas

Since 0.2.0-alpha1 jgitver provides a mechanism to retrieve several useful information after a version calculation, for example the git commitID, the branch name of HEAD (if any), the list of tags used for the version resolution and so on.

You can query GitVersionCalculator#meta(Metadatas) in order to retrieve the data associated to a given so called Metadatas (click the link to browse all available Metadatas).

Build & release

Normal build

Release

Maintaining up-to-date dependencies

Execute following command to find new dependencies

mvn versions:display-dependency-updates