Git pre-commit钩子失效排查指南

当Git pre-commit钩子失效时，可以按照以下步骤进行排查：

1. 检查钩子文件是否存在

ls -la .git/hooks/pre-commit

• 确认文件是否存在且有可执行权限
• 如果没有，从模板复制或创建新文件：

cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

2. 验证钩子文件内容

• 确保文件开头有正确的shebang（如#!/bin/sh或#!/usr/bin/env bash）
• 检查脚本逻辑是否正确，特别是退出代码（非0表示失败）

3. 检查全局钩子配置

git config --global core.hooksPath

• 如果设置了全局hooks路径，可能会覆盖本地钩子
• 取消设置：

git config --global --unset core.hooksPath

4. 测试钩子执行

手动运行钩子脚本：

.git/hooks/pre-commit

观察输出和返回码（echo $?）

5. 检查Git版本

git --version

• 某些旧版本Git可能有钩子执行问题

6. 检查文件系统权限

• 确保.git/hooks目录和pre-commit文件对当前用户可读可执行

7. 查看Git详细输出

GIT_TRACE=1 git commit -m "test"

这会显示钩子是否被执行以及执行过程中的详细信息

8. 常见问题解决方案

• 钩子被跳过：检查是否有--no-verify参数被使用
• 脚本权限问题：确保脚本可执行且无语法错误
• 环境变量问题：钩子可能依赖的环境变量在Git上下文中不存在
• 换行符问题：Windows下注意CRLF/LF转换

9. 使用调试模式

在pre-commit脚本开头添加：

set -x  # 开启调试模式

或

exec > /tmp/pre-commit.log 2>&1  # 重定向输出到日志文件

如果问题仍然存在，建议简化pre-commit脚本到最基本形式，逐步添加功能以定位问题。