Spring Boot+Gradle项目Git pre-commit Hook无法正常工作如何解决？

问题场景 #

在Spring Boot+Gradle项目中配置Git pre-commit hook时遇到以下问题：

• 已在scripts目录下创建pre-commit脚本，内容如下：

#!/bin/sh

echo "*****Running unit tests******"

git stash -q --keep-index

./gradlew test

status=$?

git stash pop -q

echo "*****Done with unit tests******"

exit $status

• 已在build.gradle中定义installLocalGitHook复制任务，并设置build.dependsOn installLocalGitHook，配置如下：

task installLocalGitHook(type: Copy){
from new File(rootProject.rootDir, 'scripts/pre-commit')
into { new File(rootProject.rootDir, '.git/hooks')}
fileMode 0775
}

build.dependsOn installLocalGitHook

• 执行./gradlew build时，installLocalGitHook任务未自动运行，脚本未复制到.git/hooks目录；但手动执行./gradlew installLocalGitHook时一切正常。

可能的原因及解决办法 #

1. Gradle任务依赖未正确绑定到构建生命周期 #

默认情况下，build任务属于Gradle的build生命周期，但如果依赖的任务没有被纳入到正确的执行链中，Gradle可能跳过它。

解决办法：将任务绑定到preBuild阶段
把installLocalGitHook关联到build任务执行前的preBuild阶段，确保它在构建开始前就运行：

task installLocalGitHook(type: Copy){
    from new File(rootProject.rootDir, 'scripts/pre-commit')
    // 去掉into的闭包写法，直接用File对象更简洁
    into new File(rootProject.rootDir, '.git/hooks')
    fileMode 0775
}

// 让preBuild阶段依赖该任务，确保build执行前先安装钩子
preBuild.dependsOn installLocalGitHook

或者显式声明任务的输入输出，让Gradle能正确判断任务是否需要执行（避免因为UP-TO-DATE判断跳过）：

task installLocalGitHook(type: Copy){
    from new File(rootProject.rootDir, 'scripts/pre-commit')
    into new File(rootProject.rootDir, '.git/hooks')
    fileMode 0775
    
    // 声明输入输出文件/目录，帮助Gradle追踪变化
    inputs.file(new File(rootProject.rootDir, 'scripts/pre-commit'))
    outputs.dir(new File(rootProject.rootDir, '.git/hooks'))
}

build.dependsOn installLocalGitHook

2. .git目录被Gradle忽略导致任务被标记为UP-TO-DATE #

.git目录是Git的私有目录，Gradle默认会忽略这类目录的变化，可能导致Gradle认为installLocalGitHook任务已经是最新状态，从而跳过执行。

解决办法：强制任务每次都执行
通过outputs.upToDateWhen { false }让Gradle不做最新状态判断，每次构建都运行该任务：

task installLocalGitHook(type: Copy){
    from new File(rootProject.rootDir, 'scripts/pre-commit')
    into new File(rootProject.rootDir, '.git/hooks')
    fileMode 0775
    
    // 强制任务每次执行，不判断是否为最新
    outputs.upToDateWhen { false }
}

build.dependsOn installLocalGitHook

3. 多模块项目的任务作用域问题 #

如果是多模块Spring Boot项目，根项目定义的任务可能没有被子模块的build任务正确依赖。

解决办法：让所有子模块的build任务依赖根项目的钩子安装任务
在根项目的build.gradle中添加如下配置：

task installLocalGitHook(type: Copy){
    from new File(rootDir, 'scripts/pre-commit')
    into new File(rootDir, '.git/hooks')
    fileMode 0775
}

// 遍历所有子模块，让它们的build任务都依赖根项目的installLocalGitHook
subprojects {
    build.dependsOn rootProject.installLocalGitHook
}

验证步骤 #

可以通过以下方式确认配置是否生效：

• 执行./gradlew build --dry-run，查看输出的任务执行序列，确认installLocalGitHook是否在其中
• 执行./gradlew tasks --all，查看installLocalGitHook的依赖关系，确认是否和build任务正确关联
• 查看./gradlew build的控制台输出，检查是否有installLocalGitHook的执行日志，或者是否被标记为UP-TO-DATE

内容的提问来源于stack exchange，提问作者Swapnil Thamake