用 pre-commit 给 Python 项目加一道提交前的自动检查
最近在一个多人协作的小型 Python 项目里,代码评审时总有一半的评论在说格式问题:缩进不统一、import 顺序乱、行尾多余空格、偶尔还有调试用的 print 混进主分支。这类问题不难,但很耗评审者的耐心。后来我们给仓库加上了 pre-commit,让这些检查在每次 git commit 时自动完成,评审终于可以把注意力放回逻辑本身。下面记录一下配置过程和踩过的坑。
一、pre-commit 是什么
pre-commit 是一个管理 Git 钩子的框架。它读取仓库根目录下的 .pre-commit-config.yaml,在提交前按顺序运行配置好的检查工具。每个工具都运行在独立的虚拟环境里,团队成员不需要手动安装 black、ruff 这些依赖,版本也由配置文件统一锁定。
二、三步完成配置
- 安装:pip install pre-commit
- 在仓库根目录新建 .pre-commit-config.yaml,配置 pre-commit-hooks(trailing-whitespace、end-of-file-fixer、check-yaml、check-added-large-files)和 ruff-pre-commit(ruff --fix、ruff-format)两个仓库,并用 rev 锁定版本。
- 安装钩子:pre-commit install
之后每次 git commit,pre-commit 只会检查本次暂存的文件。如果工具自动修改了文件,提交会被中止,重新 git add 后再提交即可。
三、第一次全量检查
新接入的老仓库建议先跑一次 pre-commit run --all-files。我们第一次运行修改了四十多个文件,主要是行尾空格和 import 排序。建议把这次全量格式化单独作为一个提交,提交信息写清楚“仅格式化,无逻辑变更”,并把哈希写进 .git-blame-ignore-revs,方便以后 git blame 时跳过它。
四、踩过的几个坑
- 首次运行很慢:pre-commit 需要下载并创建各工具的环境,第一次可能要一两分钟,之后会使用缓存。网络不稳定时可以配置 pip 镜像源。
- 版本过旧:rev 字段写死了版本,时间久了工具会落后。定期执行 pre-commit autoupdate 即可升级,升级后最好再全量跑一次。
- 有人绕过检查:git commit --no-verify 可以跳过钩子。所以只靠本地钩子不够,我们在 CI 里也加了一步 pre-commit run --all-files,保证主分支始终干净。
- 大文件误提交:check-added-large-files 默认阈值是 500KB,曾经帮我们拦下了一个误放进仓库的测试数据集。确实需要较大文件时,可以通过 args 调整阈值,或者改用 Git LFS。
五、效果
接入一个月后,评审意见里关于格式的评论几乎消失,新成员也不需要先读一遍代码规范文档才能提交代码。整个配置文件不到二十行,投入很小,收益却很明显。如果你的团队也经常在评审里讨论空格和换行,不妨试试 pre-commit。
- 点赞
- 收藏
- 关注作者
评论(0)