Table of Contents

• githook-maven-plugin
  • Usage
    • Additional Configuration Options
  • Why should I use this plugin?
  • Implementation
  • Caveats
  • Targeting the Latest SNAPSHOT

githook-maven-plugin

Maven plugin to configure and install local git hooks. It’s always a good idea to check your changes before committing them: run unit tests, perform the build, etc. However, such check-lists may be easily overlooked, especially in big projects. To get rid of the human factor, they should be somehow forced and automated. The best way is to implement such verification on the project infrastructure level. However, sometimes there’s no infrastructure or it doesn’t allow to implement that. For the latter there are git client hooks.

Usage

The following adds a pre-commit hook that executes a mvn test before every commit:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.sandbox</groupId>
    <artifactId>githook-test</artifactId>
    <version>1.0.0</version>
    <build>
        <plugins>
            <plugin>
                <groupId>io.github.phillipuniverse</groupId>
                <artifactId>githook-maven-plugin</artifactId>
                <version>1.0.5</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>install</goal>
                        </goals>
                        <configuration>
                            <hooks>
                                <pre-commit>
                                    echo "Validating..."
                                    exec mvn test
                                </pre-commit>
                            </hooks>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

The plugin provides a single goal: install. By default this is mapped to the initialize phase of the Maven Lifecycle:

<executions>
    <execution>
        <goals>
            <goal>install</goal>
        </goals>
    </execution>
</executions>

To configure hooks provide the following configuration for the execution where hook-name corresponds to a valid Git client hook:

<configuration>
  <hooks>
    <pre-commit>script</pre-commit>
    ...
  </hooks>
</configuration>

⚠️	The plugin rewrites existing hooks with the same name

Additional Configuration Options

Configuration Property	User Property	Description	Default Value
skip	githook.plugin.skip	Skips execution of the plugin altogether	false
skipRepositoryCheck	githook.plugin.skipRepositoryCheck	Whether or not the plugin should fail if the project being built is not in a Git repository	false

Why should I use this plugin?

Because it deals with the problem of providing hook configuration to the repository, and automates their installation.

Implementation

The idea is to keep somewhere a mapping between the hook name and the script, for each hook name create a respective file in .git/hooks, containing that script when the project initializes. "Initializes" — is quite a polymorphic term, but when it’s a maven project, then it likely means initial lifecycle phase. In the majority of cases, it will be enough to map the plugin on "initialize" phase, but you can still create any other custom execution.

Caveats

1. Users can still clone the repository and interact with it without performing any Maven commands and thus any hooks will be ignored

2. Users can delete the .git/hooks files manually, or still commit with git commit --no-verify to skip all hook executions

Targeting the Latest SNAPSHOT

Updates to the master branch are autodeployed to the Maven central snapshots repository. To get the latest unreleased version, add a pluginRepository to your pom.xml:

<pluginRepositories>
  <pluginRepository>
    <id>central-snapshots</id>
    <releases><enabled>false</enabled></releases>
    <snapshots><enabled>true</enabled></snapshots>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
  </pluginRepository>
</pluginRepositories>

💡	The latest snapshot version is in the pom.xml of this repository