trandersen-ufst / gaps

Git information As Plain Source

gaps - Git information As Plain Source

tl;dr: Capture git metadata in Java source at build time.

Why?

In the modern world of continuous integration and deployment, the traditional approach with using Maven versions turns out to be too inflexible as this version number is hard coded in the POM. It is therefore typical to identify the sources by git commit which is typically only available at build time , and that information also needs to be present at runtime to allow linking back to the corresponding sources. Hence a mechanism is needed to persist the git metadata during the build.

The existing Java tooling typically do this, by extracting the metadata from git during the when running the build process compiling the sources and put it in a resource file. This is usually not available during development as IDE's use their own internal build system. This typically mean that git metadata is not fully integrated during local development but only when building deployments, typically by a build server.

How?

This project uses another approach inspired by Dagger 2, namely by doing the magic transparently at compilation time by generating a Java class containing constants with the necessary metadata, which can then be accessed completely without any kind of magic at any time in the project for what is necessary, like logging at startup time.

Technically, this is done by having an annotation processor that is triggered by @Gaps and then queries the classloader where we are in the file system, and uses that to locate the .git folder. Then use jgit to read in the repository metadata and jpoet to generate the Java class with the desired constants in the current project.

Usage

Put the gaps-processor artifact on the classpath. The compile scope ensures all the magic is gone after the end of compilation.

    <dependency>
        <groupId>com.github.users.ravn.gaps</groupId>
        <artifactId>gaps-processor</artifactId>
        <version>0.0-SNAPSHOT</version>
        <scope>compile</scope>
    </dependency>

Sample run:

mvn clean install
mvn -q -pl gaps-example exec:java

For a given class bar.Foo, annotate it with @gaps to have bar.FooGaps automatically generated by the compiler. FooGaps then provide several constants with git metadata. See demo/Main.java for a functional example.

This is still on a proof-of-concept state, and feedback is needed to identify what is actually needed and in what form?

Examples:

• Should dates be as Date or String?
• Do we realistically need more metadata than for current commit? (Parents/full tree/how long ago?)
• Would a toString() realistically be useful?
• Should this be donated to Spring Boot or Google code?
• How can the documentation be improved?

Feel free to open issues!

Helpful links for maintainers:

• https://cloudogu.com/en/blog/Java-Annotation-Processors_1-Intro
• https://github.com/pellaton/spring-configuration-validation-processor
• https://www.baeldung.com/java-annotation-processing-builder