Welcome to jgitver’s documentation!¶
The main documentation for the site is organized into a couple sections:
Introduction¶
jgitver in essence is a set of tool providing auto-computation of projects versioning and comes with plugins for maven-usage and gradle-usage.
For those who can wait go directly to maven-usage or gradle-usage pages.
Main features include:
- project version calculation (semver compatible)
- standardized but configurable computations
- 0 file modification and thus 0 additional commit
- plugins for maven-usage and gradle-usage
When activated, jgitver is able for example to compute version number à la maven as following:
jgitver in ‘maven’ mode
- Using a maven like configuration, it is possible for your project to automatically:
- use SNAPSHOTS
- have dedicated versioning for branch
- have released versions for release tags
but depending on your needs, you could also configure jgitver to produce:
jgitver producing unique versions for each commit
- In this mode:
- versions are suffixed with the distance to the base tag
- have dedicated versioning for branch
- have released versions for release tags
Clean git history¶
jgitver has been created with DRY & KISS principles in mind especially to keep a clean git history.
Having this in mind, jgitver has been built to allow to NOT modify any project descriptor (pom.xml or build.gradle).
The benefits from the above:
- no pollution of git history for unnecessary commits. Your git log contains ONLY business changes ; tag & deploy actions are enough for your project
- project version follows defined (but configurable) guidelines
- version can be automatically differentiated when working in branch
To summarize if you are familiar with the following unnecessary commits (in red) from maven release plugin
Then be happy to hear that git tag and mvn deploy || gradle publish are just enough when using jgitver.
Maven usage¶
jgitver operates as a maven core extension and needs a per project installation.
Installing is as simple as running the following command from the root directory of your project (see below for other methods):
sh -c "$(curl -fsSL https://raw.githubusercontent.com/jgitver/jgitver-maven-plugin/master/src/doc/scripts/install.sh)"
Congratulations, your project now uses jgitver, run mvn validate to be convinced that jgitver works
$ 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
Note
As jgitver uses the maven core extension mechanism it requires a maven version >= 3.3.2
All installation methods¶
All the installation scripts below will use the latest version available ; if you are updating find the latest version here or there.
curl¶
sh -c "$(curl -fsSL https://raw.githubusercontent.com/jgitver/jgitver-maven-plugin/master/src/doc/scripts/install.sh)"
wget¶
sh -c "$(wget https://raw.githubusercontent.com/jgitver/jgitver-maven-plugin/master/src/doc/scripts/install.sh -O -)"
manual installation¶
- 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.3.0</version>
</extension>
</extensions>