https://github.com/emergentdotorg/gittle
Tools for generating and manipulating maven project versions from Git logs
https://github.com/emergentdotorg/gittle
git maven semantic-versioning
Last synced: 3 months ago
JSON representation
Tools for generating and manipulating maven project versions from Git logs
- Host: GitHub
- URL: https://github.com/emergentdotorg/gittle
- Owner: emergentdotorg
- License: apache-2.0
- Created: 2025-09-06T19:53:09.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-10-09T07:38:55.000Z (9 months ago)
- Last Synced: 2026-01-14T17:16:45.856Z (6 months ago)
- Topics: git, maven, semantic-versioning
- Language: Java
- Homepage:
- Size: 106 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gittle
Tools for generating and manipulating maven project versions from Git logs.
## Overview
This extension will set the project `revision` property based on the Git commit history.
The version format pattern is configurable and allows for using values such as the Git hash, branch name etc.
## Configuration
This is a maven build core extension that can -
- Participate in maven build lifecycle
- Automatically set the building project's version
- No explicit mojo executions needed to set the version
- Project's POM remain unchanged
To use as a maven build extension, create (or modify) `extensions.xml` file in `${project.baseDir}/.mvn/` to have:
```xml
org.emergent.gittle
gittle-maven-extension
${latest-version-here}
```
Then change the pom version (or parent version) element values to '${revision}', and add a default value for the
`revision` property:
A single-module project example:
```xml
net.sample
app-1
${revision}
0.0.1-SNAPSHOT
```
A multi-module project example:
```xml
net.sample
sample-parent
${revision}
lib-a
0.0.1-SNAPSHOT
```
```xml
net.sample
sample-parent
${revision}
lib-a
```
See an example test project
at [project-with-extension](gittle-maven-extension/src/test/resources/project-with-extension/).
With just that configuration, next time your project runs any maven goals, you should see version from this module
is used by Maven reactor. Try running `mvn package` on your project.
## Version Pattern Customization
The default version pattern is `%t(-%B)(-%C)(-%S)(+%H)(.%D)`, but this can be customized by setting the
`gittle.versionPattern` property in the `.mvn/gittle-maven-extension.properties` file.
The following example will generate versions as `major.minor.patch+shorthash`, eg. `1.2.3+a5a29f8`.
Example configuration for version pattern
```properties
# Will generate something like 1.2.3+a5a29f8
gittle.versionPattern=%t+%h
```
Available Tokens for Version Pattern
Note: Any token may be wrapped within parenthesis, along with other literal characters. If the token evaluates to
empty for strings or zero (0) for numbers then the entire group is omitted, for any other value the entire group is
kept excluding the surrounding parenthesis.
| Token | Description |
|-------|----------------------------------------------------------------------|
| %t | Most recent tag name (by default dropping any 'v' prefix) |
| %b | Branch name |
| %B | Branch name (empty when a release branch, by default main or master) |
| %c | Commit count (since most recent tag) |
| %C | Commit count (empty when commit count would be zero) |
| %h | Short hash ref |
| %H | Short hash ref (empty when release branch and commit count is zero) |
| %f | Full hash ref |
| %F | Full hash ref (empty when release branch and commit count is zero) |
| %S | 'SNAPSHOT' (empty when commit count is zero) |
| %D | 'dirty' (empty when no uncommited changes exist in workspace) |
## Version Pattern Examples
| Pattern | %t = 1.2.3
%b = main
%c = 0 | %b = devel | %c = 5 | %b = devel
%c = 5 |
|-------------------|-------------------------------------|-------------|------------------|------------------------|
| %t(-%B)(-%C)(-%S) | 1.2.3 | 1.2.3-devel | 1.2.3-5-SNAPSHOT | 1.2.3-devel-5-SNAPSHOT |
## Generated Version Access
This extension adds all the resolved properties to *Maven properties* during build cycle.
```properties
# example injected maven properties
gittle.resolved.branch=main
gittle.resolved.hash=67550ad6a64fe4e09bf9e36891c09b2f7bdc52f9
gittle.resolved.hashShort=67550ad
gittle.resolved.tagVersion=0.0.1
gittle.resolved.commits=0
gittle.resolved.dirty=false
gittle.resolved.version=0.0.1
```
You may use these properties in maven pom file, for example as `${gittle.resolved.branch}` to access git branch name.