diff --git a/README.md b/README.md index e798b010..6d031fc0 100644 --- a/README.md +++ b/README.md @@ -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 -io.github.git-commit-id -git-commit-id-maven-plugin -``` -older version (4.x.x or older) are available via: -```xml -pl.project13.maven -git-commit-id-plugin -``` - -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 - - - sonatype-snapshots - Sonatype Snapshots - https://s01.oss.sonatype.org/content/repositories/snapshots/ - - + + io.github.git-commit-id + git-commit-id-maven-plugin + 9.0.1 + + + get-the-git-infos + + revision + + initialize + + + + true + ${project.build.outputDirectory}/git.properties + full + + ``` -Older Snapshots (prior version 5.X) are available via `https://oss.sonatype.org/content/repositories/snapshots/`. - - -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, @@ -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 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. diff --git a/docs/access-version-info-at-runtime.md b/docs/access-version-info-at-runtime.md new file mode 100644 index 00000000..4736c48c --- /dev/null +++ b/docs/access-version-info-at-runtime.md @@ -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 + + org.codehaus.mojo + templating-maven-plugin + 3.0.0 + + + + filter-sources + + generate-sources + + + +``` + +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 + + + true + + ${project.build.outputDirectory}/git.properties + +``` + +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); + } +} +``` diff --git a/docs/using-the-plugin.md b/docs/configuration-and-properties.md similarity index 75% rename from docs/using-the-plugin.md rename to docs/configuration-and-properties.md index 79fa9c98..2faa46f7 100644 --- a/docs/using-the-plugin.md +++ b/docs/configuration-and-properties.md @@ -1,43 +1,34 @@ -Overview -==================================================================================================================== +# Configuration & Properties This file should give you an overview on how to use the generated properties within your project. -Basic configuration / Basic usage of the plugin ----------------- -It's really simple to setup this plugin; below is a sample plugin configuration that you may paste into the `` section of your **pom.xml** to get started quickly. -This will get you a properties file `git.properties` with build time, project version and git commit id (both abbreviated and full). - -For more in-depth explanation of all options read the next section. +## Basic Configuration +Below is a sample configuration that will write a properties file `git.properties` containing all the git version info to the output directory of your project. +Note that the plugin binds to the initialize phase by default, so that all git properties are available for use throughout the build lifecycle. ```xml - - io.github.git-commit-id - git-commit-id-maven-plugin - 5.0.0 - - - get-the-git-infos - - revision - - initialize - - - - true - ${project.build.outputDirectory}/git.properties - - ^git.build.(time|version)$ - ^git.commit.id.(abbrev|full)$ - - full - - + + io.github.git-commit-id + git-commit-id-maven-plugin + 9.0.1 + + + get-the-git-infos + + revision + + initialize + + + + true + ${project.build.outputDirectory}/git.properties + full + + ``` -Configuration options in-depth / Full usage of the plugin ----------------- -It's really simple to setup this plugin; below is a sample pom that you may base your **pom.xml** on. Note that it binds to the initialize phase by default such that all Git properties are available for use throughout the build lifecycle. +## Full Configuration +Below is a sample of a full `pom.xml` using the plugin. ```xml @@ -74,7 +65,7 @@ It's really simple to setup this plugin; below is a sample pom that you may base io.github.git-commit-id git-commit-id-maven-plugin - 5.0.0 + 9.0.1 get-the-git-infos @@ -163,11 +154,6 @@ It's really simple to setup this plugin; below is a sample pom that you may base ``` -Based on the above part of a working POM you should be able to figure out the rest, I mean you are a maven user after all... ;-) - -All options are documented in the code, so just use `ctrl + q` (intellij @ linux) or `f1` (intellij @ osx) when writing the options in pom.xml - you'll get examples and detailed information about each option (even more than here). - - Validation Usage Example ---------------- @@ -223,8 +209,7 @@ You can also change the default phase of each execution by adding a `phase` defi *Note* : In order to be able to validate the generated git-properties inside the pom itself you may need to set the configuration `true`. -Generated properties +All Properties --------------------- -Refer to [this](https://github.com/git-commit-id/git-commit-id-plugin-core/blob/master/src/main/java/pl/project13/core/GitCommitPropertyConstant.java) -to get an overview what properties can be generated by the plugin. -Keep in mind that all properties listed there will be prefixed with the configurable prefix (`git.` by default). +Refer to [this](https://github.com/git-commit-id/git-commit-id-plugin-core/blob/master/src/main/java/pl/project13/core/GitCommitPropertyConstant.java) to view all properties that can be generated by the plugin. +Keep in mind that all properties will be prefixed with the configurable prefix (`git.` by default). diff --git a/docs/old-versions.md b/docs/old-versions.md new file mode 100644 index 00000000..8fa35859 --- /dev/null +++ b/docs/old-versions.md @@ -0,0 +1,70 @@ +# Old Versions + +## Relocation of the Project +Older versions (4.x.x or older) are available via: +```xml +pl.project13.maven +git-commit-id-plugin +``` + +## Minimum Java Version +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 | + + +## Minimum Maven Version +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 actually 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. diff --git a/docs/snapshots.md b/docs/snapshots.md new file mode 100644 index 00000000..4dd665d1 --- /dev/null +++ b/docs/snapshots.md @@ -0,0 +1,15 @@ +# 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... :-) + +```xml + + + sonatype-snapshots + Sonatype Snapshots + https://s01.oss.sonatype.org/content/repositories/snapshots/ + + +``` + +Older Snapshots (prior version 5.X) are available via `https://oss.sonatype.org/content/repositories/snapshots/`. diff --git a/docs/use-cases.md b/docs/use-cases.md index d3d94245..2f75266c 100644 --- a/docs/use-cases.md +++ b/docs/use-cases.md @@ -33,7 +33,7 @@ With the current version of the validation the user can decide if the build shou For flexibility and due to the fact that this validation has a different scope than the git-commit-id-maven-plugin this validation needs to be configured as additional execution inside the configuration of the pom.xml. Once configured, the validation is executed during the verification-phase. However since the validation is done in a separate execution the phase can easily be changed by adding the desired phase to the execution configuration. -Note that this feature needs to be enabled properly, before it can be used. Checkout the `Validation Usage Example` in the [using the plugin](using-the-plugin.md) guide to find out more. +Note that this feature needs to be enabled properly, before it can be used. Checkout the `Validation Usage Example` in the [Configuration & Properties](configuration-and-properties.md) guide to find out more. Other ----- diff --git a/docs/using-the-plugin-in-more-depth.md b/docs/using-the-plugin-in-more-depth.md deleted file mode 100644 index f654c807..00000000 --- a/docs/using-the-plugin-in-more-depth.md +++ /dev/null @@ -1,281 +0,0 @@ -Overview -========================================================== -This file should give you an overview on how to use the generated properties within your project. -Essentially every user can chose between the following alternatives: -* use plain resource filtering from maven -* use resource filtering from maven Maven in combination with Spring beans -* have the plugin generate a `git.properties` inside your artifact - -The following should give you a broad overview about the different cases. - -Maven resource filtering ------------------------------------------------------------ -You can setup this plugin to craft your own properties file. Such behaviour can be achieved by enabeling resources filtering inside your pom. - -As an example consider that you want to place your own custom properties in your project under `/src/main/resources` (and call it **git.properties** for example). -Enable resource filtering, by configuring -``` - - - src/main/resources - true - - **/*.properties - **/*.xml - - - -``` -Also include such a custom crafted properties file with unresolved property values like `${git.tags}`. -Example: - -``` -git.tags=${git.tags} -git.branch=${git.branch} -git.local.branch.ahead=${git.local.branch.ahead} -git.local.branch.behind=${git.local.branch.behind} -git.dirty=${git.dirty} -git.remote.origin.url=${git.remote.origin.url} - git.commit.id=${git.commit.id} - OR (depends on commitIdGenerationMode) - git.commit.id.full=${git.commit.id.full} -git.commit.id.abbrev=${git.commit.id.abbrev} -git.commit.id.describe=${git.commit.id.describe} -git.commit.id.describe-short=${git.commit.id.describe-short} -git.commit.user.name=${git.commit.user.name} -git.commit.user.email=${git.commit.user.email} -git.commit.message.full=${git.commit.message.full} -git.commit.message.short=${git.commit.message.short} -git.commit.time=${git.commit.time} -git.closest.tag.name=${git.closest.tag.name} -git.closest.tag.commit.count=${git.closest.tag.commit.count} - -git.build.user.name=${git.build.user.name} -git.build.user.email=${git.build.user.email} -git.build.time=${git.build.time} -git.build.host=${git.build.host} -git.build.version=${git.build.version} -git.build.number=${git.build.number} -git.build.number.unique=${git.build.number.unique} -``` - -Maven will replace the placeholders with the appropriate properties during the build. - -The `git` prefix may be configured in the plugin declaration above. - -An easier way might be using the generation of a properties file via `generateGitPropertiesFilename`, but thats fully up to you. - -Maven resource filtering + Spring = GitRepositoryState Bean ------------------------------------------------------------ -You'll most probably want to wire these plugins somehow to get easy access to them during runtime. We'll use spring as an example of doing this. -Start out with with adding the above steps to your project, next paste this **git-bean.xml** into the `/src/main/resources/` directory (or any other, just adjust the paths later on): - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -And here's the source of the bean we're binding here: - -```java -package pl.project13.maven.example.git; - -import org.codehaus.jackson.annotate.JsonWriteNullProperties; - -/** -* A spring controlled bean that will be injected -* with properties about the repository state at build time. -* This information is supplied by my plugin - pl.project13.maven.git-commit-id-maven-plugin -*/ -@JsonWriteNullProperties(true) -public class GitRepositoryState { - String tags; // =${git.tags} // comma separated tag names - String branch; // =${git.branch} - String dirty; // =${git.dirty} - String remoteOriginUrl; // =${git.remote.origin.url} - - String commitId; // =${git.commit.id.full} OR ${git.commit.id} - String commitIdAbbrev; // =${git.commit.id.abbrev} - String describe; // =${git.commit.id.describe} - String describeShort; // =${git.commit.id.describe-short} - String commitUserName; // =${git.commit.user.name} - String commitUserEmail; // =${git.commit.user.email} - String commitMessageFull; // =${git.commit.message.full} - String commitMessageShort; // =${git.commit.message.short} - String commitTime; // =${git.commit.time} - String closestTagName; // =${git.closest.tag.name} - String closestTagCommitCount; // =${git.closest.tag.commit.count} - - String buildUserName; // =${git.build.user.name} - String buildUserEmail; // =${git.build.user.email} - String buildTime; // =${git.build.time} - String buildHost; // =${git.build.host} - String buildVersion; // =${git.build.version} - String buildNumber; // =${git.build.number} - String buildNumberUnique; // =${git.build.number.unique} - - public GitRepositoryState() { - } - /* Generate setters and getters here */ -} -``` - -The source for it is also on the repo of this plugin. Of course, *feel free to drop out the jackson annotation* if you won't be using it. - -The last configuration related thing we need to do is to load up this bean in your appContext, so open up your **applicationContext.xml** or whatever you call it in your project and add these lines in the section: - - - - -Of course, you may adjust the paths and file locations as you please, no problems here... :-) -*Now you're ready to use your GitRepositoryState Bean!* Let's create an sample **Spring MVC Controller** to test it out: - -```java -@Controller -@RequestMapping("/git") -public class GitService extends BaseWebService { - - @Autowired - GitRepositoryState gitRepoState; - - @RequestMapping("/status") - public ModelAndView checkGitRevision() throws WebServiceAuthenticationException { - ServerResponse response = new ServerResponse(gitRepoState); - return createMAV(response); - } -} -``` - -Don't mind the createMAV and responses stuff, it's just example code. And feel free to use constructor injection, it's actually a better idea ;-) - -In the end *this is what this service would return*: - -```json - { - "tags" : "v2.1.14,testing", - "branch" : "testing-maven-git-plugin", - "dirty" : "false", - "remoteOriginUrl" : "git@github.com\:git-commit-id/git-commit-id-maven-plugin.git", - "commitId" : "787e39f61f99110e74deed68ab9093088d64b969", - "commitIdAbbrev" : "787e39f", - "describe" : "v2.1.0-2-g2346463", - "describeShort" : "v2.1.0-2", - "commitUserName" : "Konrad Malawski", - "commitUserEmail" : "konrad.malawski@java.pl", - "commitMessageFull" : "releasing my fun plugin :-) - + fixed some typos - + cleaned up directory structure - + added license etc", - "commitMessageShort" : "releasing my fun plugin :-)", - "commitTime" : "06.01.1970 @ 16:16:26 CET", - "closestTagName" : "v2.1.0", - "closestTagCommitCount" : "2", - - "buildUserName" : "Konrad Malawski", - "buildUserEmail" : "konrad.malawski@java.pl", - "buildTime" : "06.01.1970 @ 16:17:53 CET", - "buildHost" : "github.com", - "buildVersion" : "v2.1.0-SNAPSHOT" - } -``` - -The easier way: generate git.properties -======================================= -There's another way to use the plugin, it's a little bit easier I guess. First, configure it to generate a properties file on each run, goto the pom.xml and set: - -```xml - - - - - true - - - ${project.build.outputDirectory}/git.properties - -``` - -Then run the project as you would normally, the file will be created for you. And you may access it as you'd access any other properties file, for example like this: - -```java -public GitRepositoryState getGitRepositoryState() throws IOException -{ - if (gitRepositoryState == null) - { - Properties properties = new Properties(); - properties.load(getClass().getClassLoader().getResourceAsStream("git.properties")); - - gitRepositoryState = new GitRepositoryState(properties); - } - return gitRepositoryState; -} -``` - -You'd have to add such an constructor to your GitRepositoryState bean: - -```java -public GitRepositoryState(Properties properties) -{ - this.tags = String.valueOf(properties.get("git.tags")); - this.branch = String.valueOf(properties.get("git.branch")); - this.dirty = String.valueOf(properties.get("git.dirty")); - this.remoteOriginUrl = String.valueOf(properties.get("git.remote.origin.url")); - - this.commitId = String.valueOf(properties.get("git.commit.id.full")); // OR properties.get("git.commit.id") depending on your configuration - this.commitIdAbbrev = String.valueOf(properties.get("git.commit.id.abbrev")); - this.describe = String.valueOf(properties.get("git.commit.id.describe")); - this.describeShort = String.valueOf(properties.get("git.commit.id.describe-short")); - this.commitUserName = String.valueOf(properties.get("git.commit.user.name")); - this.commitUserEmail = String.valueOf(properties.get("git.commit.user.email")); - this.commitMessageFull = String.valueOf(properties.get("git.commit.message.full")); - this.commitMessageShort = String.valueOf(properties.get("git.commit.message.short")); - this.commitTime = String.valueOf(properties.get("git.commit.time")); - this.closestTagName = String.valueOf(properties.get("git.closest.tag.name")); - this.closestTagCommitCount = String.valueOf(properties.get("git.closest.tag.commit.count")); - - this.buildUserName = String.valueOf(properties.get("git.build.user.name")); - this.buildUserEmail = String.valueOf(properties.get("git.build.user.email")); - this.buildTime = String.valueOf(properties.get("git.build.time")); - this.buildHost = String.valueOf(properties.get("git.build.host")); - this.buildVersion = String.valueOf(properties.get("git.build.version")); - this.buildNumber = String.valueOf(properties.get("git.build.number")); - this.buildNumberUnique = String.valueOf(properties.get("git.build.number.unique")); -} -``` - -Yet another way to use the plugin -================================= - -Rather than reading properties files at runtime or injecting with spring, you can filter a Java source file directly and place it into `src/main/java` with an ignore, or into generated sources directory within the target directory. This has some minor advantages and disadvantages, but is useful for avoiding runtime injection or lookup from properties files that might get lost during repackaging later if used within a library. -