Lefthook 安装后 Git 提交没有触发怎么办

Lefthook 安装完成后，执行 git commit 却没有任何检查输出，通常不是 Git 提交本身坏了，而是“配置文件没被发现”“hook 被装到了另一个目录”或“hook 文件不可执行”三层之一出了偏差。按下面的路径逐层确认，通常不需要重装项目。

官方地址：https://github.com/evilmartians/lefthook

先确认项目入口和配置文件

打开项目目录后，先看当前路径、仓库根目录和配置文件。Lefthook 支持 lefthook.yml、lefthook.yaml、点文件以及 .config/lefthook.yml 等命名，但一个项目最好只保留一个主配置，避免你改了文件 A，工具实际读取文件 B。

# 在项目根目录执行，先确认 Git 根目录和可见配置
pwd
git rev-parse --show-toplevel
find . -maxdepth 2 -type f \( -name 'lefthook.yml' -o -name 'lefthook.yaml' -o -name '.lefthook.yml' -o -name 'lefthook.toml' \) -print

# 让 Lefthook 直接告诉你当前配置能否解析
lefthook validate
lefthook dump

如果 validate 报配置错误，先修 YAML/TOML 的缩进、字段名或工作目录；如果 dump 没有读到预期的 pre-commit，不要继续检查 Git hook，先回到项目根目录和文件命名这一层。

在配置文件里定位 pre-commit 任务

在编辑器中打开项目根目录的 Lefthook 配置，路径是“项目资源管理器 → lefthook.yml → pre-commit → jobs”。确认至少有一个任务，并把要检查的文件范围写清楚：

# 这是配置示例；注释说明任务和暂存文件占位符的作用
pre-commit:
  jobs:
    - name: check staged files
      # 只把本次提交暂存的文件交给检查命令
      run: ./scripts/check-staged.sh {staged_files}

这里的关键不是任务名称，而是 pre-commit 层级确实存在、命令可以在项目根目录运行。如果使用 lefthook-local.yml，还要确认它是有意覆盖本机配置，而不是误把主配置写成了 local 文件。

重新安装并检查 Git 实际 hooks 目录

在配置确认无误后，回到项目根目录执行安装。这个动作会根据当前配置创建或更新 Git hook 文件。

# 根据当前配置写入或更新 Git hooks
lefthook install

# 查看 Git 当前真正使用的 hooks 目录；空输出通常表示使用默认 .git/hooks
git config --show-origin --get core.hooksPath || true
git rev-parse --git-path hooks

# 检查 pre-commit 文件是否存在，并查看可执行权限
HOOK_DIR="$(git rev-parse --git-path hooks)"
ls -l "$HOOK_DIR/pre-commit"
test -x "$HOOK_DIR/pre-commit" && echo "hook executable"

Git 默认查找 $GIT_DIR/hooks，但 core.hooksPath 可以把目录改到仓库外或其他相对位置。因此“.git/hooks 里没有文件”不能单独证明安装失败，必须以 git rev-parse --git-path hooks 返回的目录为准。

先手动运行，再用真实提交验收

路径正确后，先绕过 Git 触发机制直接运行任务。若这里没有输出，问题仍在配置或任务命令；若这里成功，而 git commit 没反应，重点回到 hook 路径和执行权限。

# 直接运行 pre-commit 组，验证任务本身能否启动
lefthook run pre-commit

# 创建一次真实提交前，先让 Git 展示将要提交的文件
git status --short
git add path/to/changed-file
git commit -m "chore: verify lefthook"

验收时应看到 Lefthook 的任务名称、命令输出或失败提示。没有任何输出时，按这张表回到对应层：

常见问题

为什么安装了 Lefthook 还要再次执行 install？

安装二进制只解决“命令存在”，lefthook install 才会按当前配置生成或更新 Git hook 文件。

把 hook 放在 .git/hooks 就一定有效吗？

不一定。只要配置了 core.hooksPath，Git 就会按该值寻找 hook；先用 git rev-parse --git-path hooks 获取实际目录。

可以用 LEFTHOOK=0 先提交吗？

这会跳过 Lefthook 执行，只适合明确的临时场景，不能用来判断 hook 为什么没有触发。排障时应修复配置、路径或权限。