pre-commit仅提示需修改文件却未实际修改的问题排查

核心排查与修复步骤 #

1. 检查钩子的pass_filenames配置 #

很多时候钩子没实际修改文件，是因为pass_filenames被误设为false，导致钩子没接收到要处理的文件列表。打开你的.pre-commit-config.yaml，确认black、isort的配置：

repos:
- repo: https://github.com/psf/black
  rev: 24.3.0
  hooks:
  - id: black
    pass_filenames: true  # 默认是true，但如果手动修改过必须确认
- repo: https://github.com/PyCQA/isort
  rev: 5.13.2
  hooks:
  - id: isort
    pass_filenames: true

2. 验证pyproject.toml的兼容配置 #

确保black和isort的配置完全兼容，避免两者的修改互相抵消。示例正确配置：

[tool.black]
line-length = 120
target-version = ['py310']

[tool.isort]
profile = "black"  # 关键：启用black兼容模式，保证导入格式匹配
line_length = 120
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
use_parentheses = true
ensure_newline_before_comments = true

保存后手动运行black your_file.py和isort your_file.py，确认文件是否真的被修改，排除工具本身的配置问题。

3. 强制钩子执行顺序正确 #

isort必须在black之前运行——因为black会调整导入的格式，如果顺序反了，isort的修改会被black完全覆盖，最终文件看起来没变化。正确的配置顺序：

repos:
- repo: https://github.com/PyCQA/isort
  rev: 5.13.2
  hooks:
  - id: isort
- repo: https://github.com/psf/black
  rev: 24.3.0
  hooks:
  - id: black

4. 清理pre-commit缓存 #

pre-commit会缓存钩子运行环境，旧缓存可能导致新配置不生效。执行命令清理：

pre-commit clean

之后重新运行pre-commit run --all-files。

5. 验证钩子版本兼容性 #

确保black和isort的版本匹配，比如black 24.x搭配isort 5.13+是稳定兼容的组合。如果版本太旧，建议升级到最新稳定版。

6. 单钩子测试定位问题 #

单独运行某个钩子，确认是否真的修改文件：

pre-commit run isort --all-files
git status  # 检查是否有文件变更
pre-commit run black --all-files
git status  # 再次检查变更情况

通过这种方式，可以快速定位是哪个钩子未正常工作，或是钩子间的冲突导致修改被抵消。

额外注意点 #

• 确保工作目录干净（无未提交的本地修改），否则pre-commit可能跳过文件，或钩子修改被本地变更覆盖。
• 不要随意使用--no-stash参数，默认的stash机制能避免钩子修改与本地未提交文件冲突。

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