ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[] :toc:

image:https://travis-ci.org/phillipuniverse/githook-maven-plugin.svg?branch=master[link=https://travis-ci.org/phillipuniverse/githook-maven-plugin] image:https://maven-badges.herokuapp.com/maven-central/io.github.phillipuniverse/githook-maven-plugin/badge.svg?style=default[link=https://search.maven.org/artifact/io.github.phillipuniverse/githook-maven-plugin/1.0.5/maven-plugin]

= 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 https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[git client hooks].

== Usage

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

[source,xml]

<?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">

<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>

The plugin provides a single goal: install. By default this is mapped to the initialize phase of the https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html#Lifecycle_Reference[Maven Lifecycle]:

[source,xml]

To configure hooks provide the following configuration for the execution where hook-name corresponds to a https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_client_side_hooks[valid Git client hook]:

[source,xml]

WARNING: 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 https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html[lifecycle phase]. In the majority of cases, it will be enough to map the plugin on "initialize" phase, but you can still https://maven.apache.org/guides/mini/guide-configuring-plugins.html#Using_the_executions_Tag[create any other custom execution].

== Caveats

. Users can still clone the repository and interact with it without performing any Maven commands and thus any hooks will be ignored . 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:

[source,xml]

TIP: The latest snapshot version is https://github.com/phillipuniverse/githook-maven-plugin/blob/master/pom.xml#L8[in the pom.xml of this repository]