Docker镜像中Git Pre-commit钩子check-merge-conflict配置故障排查

针对你遇到的check-merge-conflict钩子无法被找到的情况，结合离线Docker环境的特殊性，我梳理了几个最可能的原因和对应的解决办法：

1. 钩子配置格式有误，尤其是entry和language字段 #

pre-commit的local钩子和远程仓库钩子的配置逻辑不同，你需要明确指定用系统环境来执行脚本，而不是让pre-commit自动构建虚拟环境（离线环境也做不到）。正确的配置应该像这样：

repos:
  - repo: local
    hooks:
      - id: check-merge-conflict
        name: Check for merge conflict markers
        # 直接调用系统Python执行脚本的绝对路径
        entry: python3 /pre-commit-hooks/pre_commit_hooks/check_merge_commit.py
        # 关键：指定language为system，告诉pre-commit用当前环境的命令执行
        language: system
        pass_filenames: true
        types: [text]

注意：如果你的容器里只有python命令（而不是python3），把entry里的python3改成python即可。

2. 脚本缺少执行权限或正确的shebang #

如果你想直接用脚本路径作为entry（比如/pre-commit-hooks/pre_commit_hooks/check_merge_commit.py），需要满足两个条件：

• 脚本开头有正确的shebang：#!/usr/bin/env python3（要和容器里的Python路径匹配）
• 脚本有可执行权限

你可以在Dockerfile里添加这两步来确保：

# 给脚本添加执行权限
RUN chmod +x /pre-commit-hooks/pre_commit_hooks/check_merge_commit.py
# 验证文件存在（可选，用于调试）
RUN ls -l /pre-commit-hooks/pre_commit_hooks/check_merge_commit.py

3. 容器内Python环境不可用或路径不匹配 #

离线环境下，容器里可能没有正确安装Python，或者python/python3命令不存在。你可以在Dockerfile里明确安装Python（比如基于Debian的镜像）：

RUN apt-get update && apt-get install -y python3 --no-install-recommends && rm -rf /var/lib/apt/lists/*

如果容器里只有python3但你习惯用python，可以加个软链接：

RUN ln -s /usr/bin/python3 /usr/bin/python

4. 路径拼写错误或仓库克隆位置不对 #

先手动验证脚本路径是否正确：进入运行中的容器，执行ls /pre-commit-hooks/pre_commit_hooks/check_merge_commit.py，看是否能找到文件。如果找不到，说明你在Dockerfile里克隆仓库的路径有误，或者仓库克隆不完整（离线环境克隆时有没有拉全分支/标签？）。

快速调试步骤 #

1. 先在容器内手动执行钩子命令：python3 /pre-commit-hooks/pre_commit_hooks/check_merge_commit.py test-file.txt，看是否能正常运行（可以先创建一个带合并冲突标记的测试文件）。
2. 手动运行pre-commit命令：pre-commit run check-merge-conflict --all-files，看具体的错误提示，比如是“command not found”还是“no such file or directory”，这能帮你快速定位问题。

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