Skip to content

Update docs #833

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 19, 2025
Merged

Update docs #833

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5dd41ca
Add docs for generating compile time constants
cliserkad Mar 8, 2025
9d6de79
refactor docs
cliserkad Mar 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 45 additions & 144 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,151 +1,56 @@
maven git commit id plugin
==================================
# maven git commit id plugin

[![Build Status](https://github.com/git-commit-id/git-commit-id-maven-plugin/workflows/Java%20CI/badge.svg?branch=master)](https://github.com/git-commit-id/git-commit-id-maven-plugin/actions)
[![Coverage Status](https://coveralls.io/repos/github/git-commit-id/git-commit-id-maven-plugin/badge.svg?branch=master)](https://coveralls.io/github/git-commit-id/git-commit-id-maven-plugin?branch=master)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.git-commit-id/git-commit-id-maven-plugin/badge.svg)](https://search.maven.org/artifact/io.github.git-commit-id/git-commit-id-maven-plugin)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.git-commit-id/git-commit-id-maven-plugin/badge.svg)](https://central.sonatype.com/artifact/io.github.git-commit-id/git-commit-id-maven-plugin)

Exports git version info to maven as properties in the `pom.xml` and as a file in the build output. Code generation and resource loading enable access to the build's version info at runtime.
Unsure if this addresses your problem? [Read about common use cases](docs/use-cases.md).

git-commit-id-maven-plugin is a plugin quite similar to [Build Number Maven Plugin](https://www.mojohaus.org/buildnumber-maven-plugin/index.html) for example but as the Build Number plugin at the time when I started this plugin only supported CVS and SVN, something had to be done.
I had to quickly develop a Git version of such a plugin. For those who don't know the plugin, it basically helps you with the following tasks and answers related questions
* Which version had the bug? Is that deployed already?
* Make your distributed deployment aware of versions
* Validate if properties are set as expected

If you are more interested in the different use-cases, feel free to [read about them in more detail](docs/use-cases.md).

Quicklinks (all relevant documentation)
==================
* [Use case documentation](docs/use-cases.md)
* [Using the plugin documentation (all details for configuration, properties, ...)](docs/using-the-plugin.md)
* [A more technical documentation on how to use the leverage the generated properties from this plugin](docs/using-the-plugin-in-more-depth.md)
* [A general documentation for git describe (usefull feature in this plugin, if you are not familiar with the command)](docs/git-describe.md)
* [All configuration options are documented inside `GitCommitIdMojo.java` as Javadoc](src/main/java/pl/project13/maven/git/GitCommitIdMojo.java#L98)
* [Frequently Asked Question (FAQ)](docs/faq.md)
* [Contributing](CONTRIBUTING.md)

Getting the plugin
==================
The plugin **is available from Maven Central** ([see here](https://search.maven.org/artifact/io.github.git-commit-id/git-commit-id-maven-plugin)), so you don't have to configure any additional repositories to use this plugin.

A detailed description of using the plugin is available in the [Using the plugin](docs/using-the-plugin.md) document. All you need to do in the basic setup is to include that plugin definition in your `pom.xml`.
For more advanced users we also prepared a [guide to provide a brief overview of the more advanced configurations](docs/using-the-plugin.md)... read on!

Relocation of the Project
------------------------
Newer version (5.x.x or more recent) are available via
```xml
<groupId>io.github.git-commit-id</groupId>
<artifactId>git-commit-id-maven-plugin</artifactId>
```
older version (4.x.x or older) are available via:
```xml
<groupId>pl.project13.maven</groupId>
<artifactId>git-commit-id-plugin</artifactId>
```

Versions
--------
The current version is **9.0.0** ([changelist](https://github.com/git-commit-id/git-commit-id-maven-plugin/issues?q=milestone%3A9.0.0)).

You can check the available versions by visiting [search.maven.org](https://search.maven.org/artifact/io.github.git-commit-id/git-commit-id-maven-plugin), though using the newest is obviously the best choice.

Plugin compatibility with Java
-------------------------------
Here is an overview of the current plugin compatibility with Java

| Plugin Version | Required Java Version |
| --------------- | ---------------------:|
| 2.1.X | Java 1.6 |
| 2.2.X | Java 1.7 |
| 3.X.X | Java 1.8 |
| 4.X.X | Java 1.8 |
| 5.X.X | Java 11 |
| 6.X.X | Java 11 |
| 7.X.X | Java 11 |
| 8.X.X | Java 11 |
| 9.X.X | Java 11 |


Plugin compatibility with Maven
-----------------------------
Even though this plugin tries to be compatible with every Maven version there are some known limitations with specific versions. Here is a list that tries to outline the current state of the art:

| Plugin Version | Minimal Required Maven version |
|----------------|:----------------------------------------------------------:|
| 2.1.X | Maven 2.2.1 up to v2.1.13; Maven 3.1.1 for any later 2.1.X |
| 2.2.X | Maven 3.1.1 up to v2.2.3; Maven 3.0 for any later 2.2.X |
| 3.X.X | Maven 3.0 |
| 4.X.X | Maven 3.0 |
| 5.X.X | Maven 3.1.0-alpha-1 |
| 6.X.X | Maven 3.1.0-alpha-1 |
| 7.X.X | Maven 3.2.5 |
| 8.X.X | Maven 3.2.5 |
| 9.X.X | Maven 3.6.3 |

Flipping the table to maven:
Please note that in theory maven 4.X should support all maven 3 plugins.
The plugin was first shipped with maven 3 support in version v2.1.14 (requiring maven version 3.1.1).
Hence the v2.1.14 should be the first supported version.
Only starting with 6.X.X this plugin was acually tested with 4.0.0-alpha-5,
but some releases might not work since Maven 4 announced that plugins require Maven 3.2.5 or later
which would only be the case for plugin versions 7.0.0 or later.

| Maven Version | Plugin Version | Notes |
|---------------|----------------:|:--------------------------------------------------:|
| Maven 3.X | any | The plugin requires at least a maven 3.1.0-alpha-1 |
| Maven 4.X | from v2.1.14 | |


Plugin compatibility with EOL Maven version
-----------------------------
End of life (EOL) Maven versions are no longer supported by Maven, nor this plugin.
The following information is made available for reference.

| Maven Version | Plugin Version | Notes |
| --------------------------- | ---------------:|:---------------------------------------------------------------------------------------------------------------:|
| Maven 2.0.11 | up to 2.2.6 | Maven 2 is EOL, git-commit-id-plugin:1.0 doesn't work -- requires maven version 2.2.1 |
| Maven 2.2.1 | up to 2.2.6 | Maven 2 is EOL |
| Maven 3.0.X | up to 4.0.5 | git-commit-id-plugin:2.1.14, 2.1.15, 2.2.0, 2.2.1, 2.2.3 doesn't work -- requires maven version 3.1.1 |
| Maven 3.0.X | up to 4.0.5 | For git-commit-id-plugin 2.2.4 or higher: works, but failed to load class "org.slf4j.impl.StaticLoggerBinder" |
| Maven 3.1.0 | any | git-commit-id-plugin:2.1.14, 2.1.15, 2.2.0, 2.2.1, 2.2.3 doesn't work -- requires maven version 3.1.1 |
| Maven 3.3.1 | any | git-commit-id-plugin:2.1.14 doesn't work |
| Maven 3.3.3 | any | git-commit-id-plugin:2.1.14 doesn't work |

Note:
As an example -- this table should be read as: For `Maven 3.1.0` `any` Plugin Version should work, besides the ones listed in the `Notes` have the limitations listed.


Getting SNAPSHOT versions of the plugin
---------------------------------------
If you really want to use **snapshots**, here's the repository they are deployed to.
But I highly recommend using only stable versions, from Maven Central... :-)

## Quick Start
The plugin is **available from [Maven Central](https://central.sonatype.com/artifact/io.github.git-commit-id/git-commit-id-maven-plugin)**. Simply add the following to your `pom.xml`:
```xml
<pluginRepositories>
<pluginRepository>
<id>sonatype-snapshots</id>
<name>Sonatype Snapshots</name>
<url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
</pluginRepository>
</pluginRepositories>
<plugin>
<groupId>io.github.git-commit-id</groupId>
<artifactId>git-commit-id-maven-plugin</artifactId>
<version>9.0.1</version>
<executions>
<execution>
<id>get-the-git-infos</id>
<goals>
<goal>revision</goal>
</goals>
<phase>initialize</phase>
</execution>
</executions>
<configuration>
<generateGitPropertiesFile>true</generateGitPropertiesFile>
<generateGitPropertiesFilename>${project.build.outputDirectory}/git.properties</generateGitPropertiesFilename>
<commitIdGenerationMode>full</commitIdGenerationMode>
</configuration>
</plugin>
```

Older Snapshots (prior version 5.X) are available via `<url>https://oss.sonatype.org/content/repositories/snapshots/</url>`.


If you just would like to see what the plugin can do, you can clone the repository and run
```
mvn clean install -Dmaven.test.skip=true && mvn clean package -Pdemo -Dmaven.test.skip=true
```
## Minimum Requirements
* Java 11
* Maven 3.6.3

## Documentation
* [Use Cases](docs/use-cases.md)
* [Configuration & Properties](docs/configuration-and-properties.md)
* [Access Version Info At Runtime](docs/access-version-info-at-runtime.md)
* [git describe](docs/git-describe.md)
* [All Configuration Options as Javadoc](src/main/java/pl/project13/maven/git/GitCommitIdMojo.java)
* [Frequently Asked Questions](docs/faq.md)
* [Contributing](CONTRIBUTING.md)
* [Releases](https://github.com/git-commit-id/git-commit-id-maven-plugin/releases)
* [Old Versions](docs/old-versions.md)
* [Snapshots](docs/snapshots.md)

Maintainers
===========
## Maintainers
This project is currently maintained thanks to: @ktoso (founder), @TheSnoozer


Notable contributions
=====================
## Notable contributions
I'd like to give a big thanks to some of these folks, for their suggestions and / or pull requests that helped make this plugin as popular as it is today:

* @mostr - for bugfixes and a framework to do integration testing,
Expand All @@ -156,25 +61,21 @@ I'd like to give a big thanks to some of these folks, for their suggestions and
* ... many others - thank you for your contributions,
* ... you! - for using the plugin :-)

Notable happy users
===================

## Notable happy users
* [neo4j](https://neo4j.com/) – graph database
* [FoundationdDB](https://www.foundationdb.org/) – another open source database
* [Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#using-boot-maven) – yes, the upstream Spring project is using us
* Akamai, Sabre, EasyDITA, and many many others,
* many others I don't know of.

License
=======
## License
<img style="float:right; padding:3px; " src="https://github.com/git-commit-id/git-commit-id-maven-plugin/raw/master/lgplv3-147x51.png" alt="GNU LGPL v3"/>

I'm releasing this plugin under the **GNU Lesser General Public License 3.0**.

You're free to use it as you wish, the full license text is attached in the LICENSE file.

Feature requests
================
## Feature requests
The best way to ask for features / improvements is [via the Issues section on GitHub - it's better than email](https://github.com/git-commit-id/git-commit-id-maven-plugin/issues) because I won't loose when I have a "million emails inbox" day,
and maybe someone else has some idea or would like to upvote your issue.

Expand Down
163 changes: 163 additions & 0 deletions docs/access-version-info-at-runtime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
# Access Version Info At Runtime
This file demonstrates multiple ways to access at runtime the git version info that was exported at buildtime.

## Generate A Java Source File with Compile Time Constants
This strategy generates a Java source file from a template and writes it to the `generated-sources` directory within the `target` directory. This is useful for avoiding runtime injection and/or lookup from properties files.

Add the [templating-maven-plugin](https://github.com/mojohaus/templating-maven-plugin) to your pom.xml:
```xml
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>templating-maven-plugin</artifactId>
<version>3.0.0</version>
<executions>
<execution>
<goals>
<goal>filter-sources</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
</plugin>
```

Add the template file to `src/main/java-templates`:
```java
package com.example.demo;

public interface Version {
String TAGS = "${git.tags}";
String BRANCH = "${git.branch}";
String DIRTY = "${git.dirty}";
String REMOTE_ORIGIN_URL = "${git.remote.origin.url}";

String COMMIT_ID = "${git.commit.id.full}";
String COMMIT_ID_ABBREV = "${git.commit.id.abbrev}";
String DESCRIBE = "${git.commit.id.describe}";
String DESCRIBE_SHORT = "${git.commit.id.describe-short}";
String COMMIT_USER_NAME = "${git.commit.user.name}";
String COMMIT_USER_EMAIL = "${git.commit.user.email}";
String COMMIT_MESSAGE_FULL = "${git.commit.message.full}";
String COMMIT_MESSAGE_SHORT = "${git.commit.message.short}";
String COMMIT_TIME = "${git.commit.time}";
String CLOSEST_TAG_NAME = "${git.closest.tag.name}";
String CLOSEST_TAG_COMMIT_COUNT = "${git.closest.tag.commit.count}";

String BUILD_USER_NAME = "${git.build.user.name}";
String BUILD_USER_EMAIL = "${git.build.user.email}";
String BUILD_TIME = "${git.build.time}";
String BUILD_HOST = "${git.build.host}";
String BUILD_VERSION = "${git.build.version}";
String BUILD_NUMBER = "${git.build.number}";
String BUILD_NUMBER_UNIQUE = "${git.build.number.unique}";
}
```
Use the same package declaration as your program's entry point, presumably in `src/main/java`.
This example would have a relative path of `src/main/java-templates/com/example/demo/Version.java`.

Use the version info as you would any other constant:
```java
package com.example.demo;

public class Main {
public static void main(String[] args) {
System.out.println("Version: " + Version.COMMIT_ID);
}
}
```

## Export a `git.properties` File Inside the Build Artifact
This strategy writes a `git.properties` file to the build artifact, and reads it at runtime.
The file will be written at buildtime and can be inspected in the build artifact.

Ensure the plugin is configured to generate the `git.properties` file:
```xml
<configuration>
<!-- Enable generation of git.properties file -->
<generateGitPropertiesFile>true</generateGitPropertiesFile>
<!-- Specify the path to write the properties file to -->
<generateGitPropertiesFilename>${project.build.outputDirectory}/git.properties</generateGitPropertiesFilename>
</configuration>
```

Include code to read the `git.properties` file at runtime and parse it:
```java
package com.example.demo;

import java.io.IOException;
import java.util.Properties;

public final class Version {
public static final String TAGS;
public static final String BRANCH;
public static final String DIRTY;
public static final String REMOTE_ORIGIN_URL;

public static final String COMMIT_ID;
public static final String COMMIT_ID_ABBREV;
public static final String DESCRIBE;
public static final String DESCRIBE_SHORT;
public static final String COMMIT_USER_NAME;
public static final String COMMIT_USER_EMAIL;
public static final String COMMIT_MESSAGE_FULL;
public static final String COMMIT_MESSAGE_SHORT;
public static final String COMMIT_TIME;
public static final String CLOSEST_TAG_NAME;
public static final String CLOSEST_TAG_COMMIT_COUNT;

public static final String BUILD_USER_NAME;
public static final String BUILD_USER_EMAIL;
public static final String BUILD_TIME;
public static final String BUILD_HOST;
public static final String BUILD_VERSION;
public static final String BUILD_NUMBER;
public static final String BUILD_NUMBER_UNIQUE;

static {
try {
Properties properties = new Properties();
properties.load(Version2.class.getClassLoader().getResourceAsStream("git.properties"));

TAGS = String.valueOf(properties.get("git.tags"));
BRANCH = String.valueOf(properties.get("git.branch"));
DIRTY = String.valueOf(properties.get("git.dirty"));
REMOTE_ORIGIN_URL = String.valueOf(properties.get("git.remote.origin.url"));

COMMIT_ID = String.valueOf(properties.get("git.commit.id.full")); // OR properties.get("git.commit.id") depending on your configuration
COMMIT_ID_ABBREV = String.valueOf(properties.get("git.commit.id.abbrev"));
DESCRIBE = String.valueOf(properties.get("git.commit.id.describe"));
DESCRIBE_SHORT = String.valueOf(properties.get("git.commit.id.describe-short"));
COMMIT_USER_NAME = String.valueOf(properties.get("git.commit.user.name"));
COMMIT_USER_EMAIL = String.valueOf(properties.get("git.commit.user.email"));
COMMIT_MESSAGE_FULL = String.valueOf(properties.get("git.commit.message.full"));
COMMIT_MESSAGE_SHORT = String.valueOf(properties.get("git.commit.message.short"));
COMMIT_TIME = String.valueOf(properties.get("git.commit.time"));
CLOSEST_TAG_NAME = String.valueOf(properties.get("git.closest.tag.name"));
CLOSEST_TAG_COMMIT_COUNT = String.valueOf(properties.get("git.closest.tag.commit.count"));

BUILD_USER_NAME = String.valueOf(properties.get("git.build.user.name"));
BUILD_USER_EMAIL = String.valueOf(properties.get("git.build.user.email"));
BUILD_TIME = String.valueOf(properties.get("git.build.time"));
BUILD_HOST = String.valueOf(properties.get("git.build.host"));
BUILD_VERSION = String.valueOf(properties.get("git.build.version"));
BUILD_NUMBER = String.valueOf(properties.get("git.build.number"));
BUILD_NUMBER_UNIQUE = String.valueOf(properties.get("git.build.number.unique"));
} catch(IOException e) {
throw new RuntimeException(e);
}
}

private Version() {}
}
```

Use the version info as you would any other constant:
```java
package com.example.demo;

public class Main {
public static void main(String[] args) {
System.out.println("Version: " + Version.COMMIT_ID);
}
}
```
Loading