A Gradle plugin enforcing pre-commit and commit-msg Git hooks configuration. Conventional-commits-ready.
Hooks are created upfront, before the execution of any task. This implies that even when importing the project into a gradle-aware IDE, the hooks are generated automatically.
This plugin must be applied to settings.gradle.kts
.
plugins {
id("org.danilopianini.gradle-pre-commit-git-hooks") version "<version>"
}
gitHooks {
// Configuration
createHooks() // actual hooks creation
}
The Groovy syntax is not officially supported.
However, since Groovy can call Kotlin, it is still possible
(though pretty cumbersome)
to use the plugin from a Groovy settings.gradle
file:
plugins {
id('org.danilopianini.gradle-pre-commit-git-hooks') version '<version>'
}
gitHooks { extension ->
extension.with {
commitMsg { context ->
context.with {
conventionalCommits { conventionalCommits ->
conventionalCommits.with {
defaultTypes()
}
}
}
}
createHooks(true)
}
}
The plugin has special support for commit-msg
and pre-commit
hooks, which are the ones most frequently used.
Conventional commits are enforced at the commit-msg
level.
Custom hooks can still be specified.
gitHooks {
preCommit {
// Configuration for pre-commit
}
hook("pre-merge-commit") {
// Configuration for pre-merge-commit
}
hook("foo") {
// Configuration for foo
}
commitMsg {
// Configuration, with conventional commits support
}
createHooks()
}
Every script can be initialized by writing its code in form of String
or by downloading it from a URL
.
Resource loading from classpath returns URL
s and can thus be used transparently.
These cases require the method from
.
The script can be enriched with more code by calling appendScript
.
Finally, the script can be required to run gradle tasks,
either requiring their success or not, through tasks
gitHooks {
path = "some/folder" // custom git repository location, defaults to the local project and scans the parents
preCommit {
// Script from a source, can be a String, URL or File
from("https://my.repo/pre-commit.sh")
// Content can be added at the bottom of the script
appendScript {
"""
echo additional lines
"""
}
}
hook("pre-merge-commit") {
from { // Creates a fresh script with a bash shebang line
"""
echo some bash code
"""
}
// Content can be added at the bottom of the script
appendScript {
"""
echo additional lines
"""
}
}
hook("foo") {
from("#!/usr/bin/env ruby") { // Custom shebang line
"""
puts "Hello, world"
"""
}
tasks("baz", "gra") // also runs tasks baz and gra, requiring their success
}
hook("baz") {
tasks("zin", "pla", requireSuccess = false) // runs tasks zin and pla, ignoring failure
tasks("wab") // then, runs task wab, requiring success
}
createHooks()
}
Conventional commits receive special treatment,
they can get configured succinctly inside the commitMsg
block.
The Default configuration supports the following commit types:
fix
, feat
, build
, chore
, ci
, docs
, perf
, refactor
, revert
, style
, test
.
gitHooks {
commitMsg { conventionalCommits() } // Applies the default conventional commits configuration
createHooks()
}
The base configuration supports only fix
and feat
gitHooks {
commitMsg {
conventionalCommits { } // Only feat and fix
}
createHooks()
}
The following shows a custom configuration,
adding custom types foo
, bar
, and baz
to fix
and feat
gitHooks {
commitMsg {
conventionalCommits {
types("foo", "bar")
types("baz")
}
}
createHooks()
}
The following custom configuration instead extends the default configuration,
adding custom types foo
and bar
.
gitHooks {
commitMsg {
conventionalCommits {
defaultTypes()
types("foo", "bar")
}
}
createHooks()
}
If you want to be able to always overwrite your hook changes pass true
to the createHooks() method
gitHooks {
preCommit {
from { // Creates a fresh script with a bash shebang line
"""
echo some bash code you have changed
"""
}
}
createHooks(true)
}