Skip to content

Latest commit

 

History

History
127 lines (104 loc) · 5.34 KB

README.adoc

File metadata and controls

127 lines (104 loc) · 5.34 KB
Raw
Table of Contents

githook maven plugin badge

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