pre-commit commit-msg阶段本地钩子无法运行求助

在MacOS系统中，通过Makefile配置Python代码仓库的pre-commit工具，期望触发Python脚本检查提交消息中的关键词。目前遇到以下问题：

• pre-commit已成功安装到.git/hooks/pre-commit，但commit-msg阶段的本地钩子始终无法启动；
• 若将阶段改为commit，脚本虽能运行但因无法获取提交消息而失败；
• 配置中的shell脚本钩子可正常执行，但Python脚本钩子无响应；
• 尝试调整always_run、pass_filenames等参数，甚至使用pre-commit run --all-files也无法触发commit-msg钩子。

Makefile #

config:
    @echo "Install Git Hooks dependencies"
    python3 -m venv env \
      && source env/bin/activate \
      && pip install pre-commit
    pre-commit install --config .pre-commit-config.yaml

安装输出 #

pre-commit install
pre-commit installed at .git/hooks/pre-commit

激活虚拟环境命令 #

source env/bin/activate

提交日志 #

% git commit -m "Testing"
check yaml...............................................................Passed
debug statements (python)............................(no files to check)Skipped
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
[main c8982a3] Testing
 3 files changed, 11 insertions(+), 4 deletions(-)

尝试过的参数 #

always_run: true # tired with false and without the arg always_run
pass_filenames: false # tired with true and without the arg pass_filename

.pre-commit-config.yaml配置 #

repos:
  - repo: local
    hooks:
      - id: validate-commit-message
        name: Validate Commit Message
        language: python
        entry: python commit_validation.py
        always_run: false
        pass_filenames: false
        stages: [commit-msg]
      - id: echo-hello
        name: Echo Hello
        entry: echo_hello.sh
        language: script
        always_run: true
        pass_filenames: false
        stages: [commit-msg]
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: check-yaml
      - id: debug-statements
      - id: end-of-file-fixer
      - id: trailing-whitespace

• 安装commit-msg类型钩子：pre-commit默认仅安装pre-commit钩子，commit-msg钩子需要单独执行命令安装。激活虚拟环境后运行：

  pre-commit install --hook-type commit-msg --config .pre-commit-config.yaml
  

  执行后检查.git/hooks/目录下是否生成commit-msg文件，这是核心修复步骤。

• 修正Python钩子的entry配置：

  1. 给commit_validation.py添加可执行权限：

     chmod +x commit_validation.py
     

  2. 在脚本开头添加shebang行，指定Python解释器：

     #!/usr/bin/env python3
     

  3. 修改pre-commit配置中的entry，去掉python前缀，直接写脚本路径：

     entry: ./commit_validation.py
     

• 验证钩子执行逻辑：手动测试commit-msg钩子，创建一个测试用的提交消息文件test_msg.txt（内容写测试提交文本），然后运行：

  ./.git/hooks/commit-msg test_msg.txt
  

  根据输出的报错信息定位脚本或配置的问题。

• 确保虚拟环境一致性：提交时确保激活了安装pre-commit的虚拟环境，或者在Makefile中把安装commit-msg钩子的命令放到虚拟环境激活的代码块内：

  config:
      @echo "Install Git Hooks dependencies"
      python3 -m venv env \
        && source env/bin/activate \
        && pip install pre-commit \
        && pre-commit install --config .pre-commit-config.yaml \
        && pre-commit install --hook-type commit-msg --config .pre-commit-config.yaml
  

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