Skip to content

Commit 9d6de79

Browse files
cliserkadcliserkad
committed
refactor docs
1 parent 5dd41ca commit 9d6de79

7 files changed

+323
-532
lines changed

‎README.md

+45-144
Original file line numberDiff line numberDiff line change
@@ -1,151 +1,56 @@
1-
maven git commit id plugin
2-
==================================
1+
# maven git commit id plugin
32

43
[![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)
54
[![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)
6-
[![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)
5+
[![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)
76

7+
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.
8+
Unsure if this addresses your problem? [Read about common use cases](docs/use-cases.md).
89

9-
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.
10-
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
11-
* Which version had the bug? Is that deployed already?
12-
* Make your distributed deployment aware of versions
13-
* Validate if properties are set as expected
14-
15-
If you are more interested in the different use-cases, feel free to [read about them in more detail](docs/use-cases.md).
16-
17-
Quicklinks (all relevant documentation)
18-
==================
19-
* [Use case documentation](docs/use-cases.md)
20-
* [Using the plugin documentation (all details for configuration, properties, ...)](docs/using-the-plugin.md)
21-
* [A more technical documentation on how to use the leverage the generated properties from this plugin](docs/using-the-plugin-in-more-depth.md)
22-
* [A general documentation for git describe (usefull feature in this plugin, if you are not familiar with the command)](docs/git-describe.md)
23-
* [All configuration options are documented inside `GitCommitIdMojo.java` as Javadoc](src/main/java/pl/project13/maven/git/GitCommitIdMojo.java#L98)
24-
* [Frequently Asked Question (FAQ)](docs/faq.md)
25-
* [Contributing](CONTRIBUTING.md)
26-
27-
Getting the plugin
28-
==================
29-
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.
30-
31-
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`.
32-
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!
33-
34-
Relocation of the Project
35-
------------------------
36-
Newer version (5.x.x or more recent) are available via
37-
```xml
38-
<groupId>io.github.git-commit-id</groupId>
39-
<artifactId>git-commit-id-maven-plugin</artifactId>
40-
```
41-
older version (4.x.x or older) are available via:
42-
```xml
43-
<groupId>pl.project13.maven</groupId>
44-
<artifactId>git-commit-id-plugin</artifactId>
45-
```
46-
47-
Versions
48-
--------
49-
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)).
50-
51-
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.
52-
53-
Plugin compatibility with Java
54-
-------------------------------
55-
Here is an overview of the current plugin compatibility with Java
56-
57-
| Plugin Version | Required Java Version |
58-
| --------------- | ---------------------:|
59-
| 2.1.X | Java 1.6 |
60-
| 2.2.X | Java 1.7 |
61-
| 3.X.X | Java 1.8 |
62-
| 4.X.X | Java 1.8 |
63-
| 5.X.X | Java 11 |
64-
| 6.X.X | Java 11 |
65-
| 7.X.X | Java 11 |
66-
| 8.X.X | Java 11 |
67-
| 9.X.X | Java 11 |
68-
69-
70-
Plugin compatibility with Maven
71-
-----------------------------
72-
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:
73-
74-
| Plugin Version | Minimal Required Maven version |
75-
|----------------|:----------------------------------------------------------:|
76-
| 2.1.X | Maven 2.2.1 up to v2.1.13; Maven 3.1.1 for any later 2.1.X |
77-
| 2.2.X | Maven 3.1.1 up to v2.2.3; Maven 3.0 for any later 2.2.X |
78-
| 3.X.X | Maven 3.0 |
79-
| 4.X.X | Maven 3.0 |
80-
| 5.X.X | Maven 3.1.0-alpha-1 |
81-
| 6.X.X | Maven 3.1.0-alpha-1 |
82-
| 7.X.X | Maven 3.2.5 |
83-
| 8.X.X | Maven 3.2.5 |
84-
| 9.X.X | Maven 3.6.3 |
85-
86-
Flipping the table to maven:
87-
Please note that in theory maven 4.X should support all maven 3 plugins.
88-
The plugin was first shipped with maven 3 support in version v2.1.14 (requiring maven version 3.1.1).
89-
Hence the v2.1.14 should be the first supported version.
90-
Only starting with 6.X.X this plugin was acually tested with 4.0.0-alpha-5,
91-
but some releases might not work since Maven 4 announced that plugins require Maven 3.2.5 or later
92-
which would only be the case for plugin versions 7.0.0 or later.
93-
94-
| Maven Version | Plugin Version | Notes |
95-
|---------------|----------------:|:--------------------------------------------------:|
96-
| Maven 3.X | any | The plugin requires at least a maven 3.1.0-alpha-1 |
97-
| Maven 4.X | from v2.1.14 | |
98-
99-
100-
Plugin compatibility with EOL Maven version
101-
-----------------------------
102-
End of life (EOL) Maven versions are no longer supported by Maven, nor this plugin.
103-
The following information is made available for reference.
104-
105-
| Maven Version | Plugin Version | Notes |
106-
| --------------------------- | ---------------:|:---------------------------------------------------------------------------------------------------------------:|
107-
| 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 |
108-
| Maven 2.2.1 | up to 2.2.6 | Maven 2 is EOL |
109-
| 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 |
110-
| 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" |
111-
| 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 |
112-
| Maven 3.3.1 | any | git-commit-id-plugin:2.1.14 doesn't work |
113-
| Maven 3.3.3 | any | git-commit-id-plugin:2.1.14 doesn't work |
114-
115-
Note:
116-
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.
117-
118-
119-
Getting SNAPSHOT versions of the plugin
120-
---------------------------------------
121-
If you really want to use **snapshots**, here's the repository they are deployed to.
122-
But I highly recommend using only stable versions, from Maven Central... :-)
123-
10+
## Quick Start
11+
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`:
12412
```xml
125-
<pluginRepositories>
126-
<pluginRepository>
127-
<id>sonatype-snapshots</id>
128-
<name>Sonatype Snapshots</name>
129-
<url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
130-
</pluginRepository>
131-
</pluginRepositories>
13+
<plugin>
14+
<groupId>io.github.git-commit-id</groupId>
15+
<artifactId>git-commit-id-maven-plugin</artifactId>
16+
<version>9.0.1</version>
17+
<executions>
18+
<execution>
19+
<id>get-the-git-infos</id>
20+
<goals>
21+
<goal>revision</goal>
22+
</goals>
23+
<phase>initialize</phase>
24+
</execution>
25+
</executions>
26+
<configuration>
27+
<generateGitPropertiesFile>true</generateGitPropertiesFile>
28+
<generateGitPropertiesFilename>${project.build.outputDirectory}/git.properties</generateGitPropertiesFilename>
29+
<commitIdGenerationMode>full</commitIdGenerationMode>
30+
</configuration>
31+
</plugin>
13232
```
13333

134-
Older Snapshots (prior version 5.X) are available via `<url>https://oss.sonatype.org/content/repositories/snapshots/</url>`.
135-
136-
137-
If you just would like to see what the plugin can do, you can clone the repository and run
138-
```
139-
mvn clean install -Dmaven.test.skip=true && mvn clean package -Pdemo -Dmaven.test.skip=true
140-
```
34+
## Minimum Requirements
35+
* Java 11
36+
* Maven 3.6.3
37+
38+
## Documentation
39+
* [Use Cases](docs/use-cases.md)
40+
* [Configuration & Properties](docs/configuration-and-properties.md)
41+
* [Access Version Info At Runtime](docs/access-version-info-at-runtime.md)
42+
* [git describe](docs/git-describe.md)
43+
* [All Configuration Options as Javadoc](src/main/java/pl/project13/maven/git/GitCommitIdMojo.java)
44+
* [Frequently Asked Questions](docs/faq.md)
45+
* [Contributing](CONTRIBUTING.md)
46+
* [Releases](https://github.com/git-commit-id/git-commit-id-maven-plugin/releases)
47+
* [Old Versions](docs/old-versions.md)
48+
* [Snapshots](docs/snapshots.md)
14149

142-
Maintainers
143-
===========
50+
## Maintainers
14451
This project is currently maintained thanks to: @ktoso (founder), @TheSnoozer
14552

146-
147-
Notable contributions
148-
=====================
53+
## Notable contributions
14954
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:
15055

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

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

168-
License
169-
=======
71+
## License
17072
<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"/>
17173

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

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

176-
Feature requests
177-
================
78+
## Feature requests
17879
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,
17980
and maybe someone else has some idea or would like to upvote your issue.
18081

‎docs/access-version-info-at-runtime.md

+163
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Access Version Info At Runtime
2+
This file demonstrates multiple ways to access at runtime the git version info that was exported at buildtime.
3+
4+
## Generate A Java Source File with Compile Time Constants
5+
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.
6+
7+
Add the [templating-maven-plugin](https://github.com/mojohaus/templating-maven-plugin) to your pom.xml:
8+
```xml
9+
<plugin>
10+
<groupId>org.codehaus.mojo</groupId>
11+
<artifactId>templating-maven-plugin</artifactId>
12+
<version>3.0.0</version>
13+
<executions>
14+
<execution>
15+
<goals>
16+
<goal>filter-sources</goal>
17+
</goals>
18+
<phase>generate-sources</phase>
19+
</execution>
20+
</executions>
21+
</plugin>
22+
```
23+
24+
Add the template file to `src/main/java-templates`:
25+
```java
26+
package com.example.demo;
27+
28+
public interface Version {
29+
String TAGS = "${git.tags}";
30+
String BRANCH = "${git.branch}";
31+
String DIRTY = "${git.dirty}";
32+
String REMOTE_ORIGIN_URL = "${git.remote.origin.url}";
33+
34+
String COMMIT_ID = "${git.commit.id.full}";
35+
String COMMIT_ID_ABBREV = "${git.commit.id.abbrev}";
36+
String DESCRIBE = "${git.commit.id.describe}";
37+
String DESCRIBE_SHORT = "${git.commit.id.describe-short}";
38+
String COMMIT_USER_NAME = "${git.commit.user.name}";
39+
String COMMIT_USER_EMAIL = "${git.commit.user.email}";
40+
String COMMIT_MESSAGE_FULL = "${git.commit.message.full}";
41+
String COMMIT_MESSAGE_SHORT = "${git.commit.message.short}";
42+
String COMMIT_TIME = "${git.commit.time}";
43+
String CLOSEST_TAG_NAME = "${git.closest.tag.name}";
44+
String CLOSEST_TAG_COMMIT_COUNT = "${git.closest.tag.commit.count}";
45+
46+
String BUILD_USER_NAME = "${git.build.user.name}";
47+
String BUILD_USER_EMAIL = "${git.build.user.email}";
48+
String BUILD_TIME = "${git.build.time}";
49+
String BUILD_HOST = "${git.build.host}";
50+
String BUILD_VERSION = "${git.build.version}";
51+
String BUILD_NUMBER = "${git.build.number}";
52+
String BUILD_NUMBER_UNIQUE = "${git.build.number.unique}";
53+
}
54+
```
55+
Use the same package declaration as your program's entry point, presumably in `src/main/java`.
56+
This example would have a relative path of `src/main/java-templates/com/example/demo/Version.java`.
57+
58+
Use the version info as you would any other constant:
59+
```java
60+
package com.example.demo;
61+
62+
public class Main {
63+
public static void main(String[] args) {
64+
System.out.println("Version: " + Version.COMMIT_ID);
65+
}
66+
}
67+
```
68+
69+
## Export a `git.properties` File Inside the Build Artifact
70+
This strategy writes a `git.properties` file to the build artifact, and reads it at runtime.
71+
The file will be written at buildtime and can be inspected in the build artifact.
72+
73+
Ensure the plugin is configured to generate the `git.properties` file:
74+
```xml
75+
<configuration>
76+
<!-- Enable generation of git.properties file -->
77+
<generateGitPropertiesFile>true</generateGitPropertiesFile>
78+
<!-- Specify the path to write the properties file to -->
79+
<generateGitPropertiesFilename>${project.build.outputDirectory}/git.properties</generateGitPropertiesFilename>
80+
</configuration>
81+
```
82+
83+
Include code to read the `git.properties` file at runtime and parse it:
84+
```java
85+
package com.example.demo;
86+
87+
import java.io.IOException;
88+
import java.util.Properties;
89+
90+
public final class Version {
91+
public static final String TAGS;
92+
public static final String BRANCH;
93+
public static final String DIRTY;
94+
public static final String REMOTE_ORIGIN_URL;
95+
96+
public static final String COMMIT_ID;
97+
public static final String COMMIT_ID_ABBREV;
98+
public static final String DESCRIBE;
99+
public static final String DESCRIBE_SHORT;
100+
public static final String COMMIT_USER_NAME;
101+
public static final String COMMIT_USER_EMAIL;
102+
public static final String COMMIT_MESSAGE_FULL;
103+
public static final String COMMIT_MESSAGE_SHORT;
104+
public static final String COMMIT_TIME;
105+
public static final String CLOSEST_TAG_NAME;
106+
public static final String CLOSEST_TAG_COMMIT_COUNT;
107+
108+
public static final String BUILD_USER_NAME;
109+
public static final String BUILD_USER_EMAIL;
110+
public static final String BUILD_TIME;
111+
public static final String BUILD_HOST;
112+
public static final String BUILD_VERSION;
113+
public static final String BUILD_NUMBER;
114+
public static final String BUILD_NUMBER_UNIQUE;
115+
116+
static {
117+
try {
118+
Properties properties = new Properties();
119+
properties.load(Version2.class.getClassLoader().getResourceAsStream("git.properties"));
120+
121+
TAGS = String.valueOf(properties.get("git.tags"));
122+
BRANCH = String.valueOf(properties.get("git.branch"));
123+
DIRTY = String.valueOf(properties.get("git.dirty"));
124+
REMOTE_ORIGIN_URL = String.valueOf(properties.get("git.remote.origin.url"));
125+
126+
COMMIT_ID = String.valueOf(properties.get("git.commit.id.full")); // OR properties.get("git.commit.id") depending on your configuration
127+
COMMIT_ID_ABBREV = String.valueOf(properties.get("git.commit.id.abbrev"));
128+
DESCRIBE = String.valueOf(properties.get("git.commit.id.describe"));
129+
DESCRIBE_SHORT = String.valueOf(properties.get("git.commit.id.describe-short"));
130+
COMMIT_USER_NAME = String.valueOf(properties.get("git.commit.user.name"));
131+
COMMIT_USER_EMAIL = String.valueOf(properties.get("git.commit.user.email"));
132+
COMMIT_MESSAGE_FULL = String.valueOf(properties.get("git.commit.message.full"));
133+
COMMIT_MESSAGE_SHORT = String.valueOf(properties.get("git.commit.message.short"));
134+
COMMIT_TIME = String.valueOf(properties.get("git.commit.time"));
135+
CLOSEST_TAG_NAME = String.valueOf(properties.get("git.closest.tag.name"));
136+
CLOSEST_TAG_COMMIT_COUNT = String.valueOf(properties.get("git.closest.tag.commit.count"));
137+
138+
BUILD_USER_NAME = String.valueOf(properties.get("git.build.user.name"));
139+
BUILD_USER_EMAIL = String.valueOf(properties.get("git.build.user.email"));
140+
BUILD_TIME = String.valueOf(properties.get("git.build.time"));
141+
BUILD_HOST = String.valueOf(properties.get("git.build.host"));
142+
BUILD_VERSION = String.valueOf(properties.get("git.build.version"));
143+
BUILD_NUMBER = String.valueOf(properties.get("git.build.number"));
144+
BUILD_NUMBER_UNIQUE = String.valueOf(properties.get("git.build.number.unique"));
145+
} catch(IOException e) {
146+
throw new RuntimeException(e);
147+
}
148+
}
149+
150+
private Version() {}
151+
}
152+
```
153+
154+
Use the version info as you would any other constant:
155+
```java
156+
package com.example.demo;
157+
158+
public class Main {
159+
public static void main(String[] args) {
160+
System.out.println("Version: " + Version.COMMIT_ID);
161+
}
162+
}
163+
```

0 commit comments

Comments
 (0)