pre-commit

多语言 Git 提交前检查框架

补充说明

pre-commit 用 .pre-commit-config.yaml 管理 Git hooks，在提交前运行格式化、lint、类型检查等。每个 hook 在自己的隔离环境中运行，避免污染项目依赖。

常用示例

pre-commit install
pre-commit install --hook-type commit-msg
pre-commit run --all-files
pre-commit run ruff --all-files
pre-commit autoupdate
pre-commit clean
pre-commit try-repo ../my-hooks --all-files

.pre-commit-config.yaml：

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.6.9
    hooks:
      - id: ruff
        args: [--fix]

易错点与排错

• 默认只检查暂存文件；要全量检查必须显式 --all-files。
• 第一次运行会下载各 hook 的环境；离线环境要提前缓存。
• rev 不固定会让不同时间安装出不同行为；定期 autoupdate 并审查。
• hook 自动修复文件后，本次提交可能不包含修复；需要重新 git add 再提交。
• commit-msg 钩子要单独 --hook-type 安装；只装默认 hook 不会生效。
• 本地 hook 不是强制门禁；CI 仍要跑同样的检查。
• 多语言 hook 需要对应的运行时；CI 基础镜像缺 Python/Node 时会失败。
• 与 husky、lefthook 同时管理 hooks 会冲突；只保留一种。

相关命令

• lefthook — 另一种 Git hooks 管理器
• commitlint — 提交信息检查
• git — 提交操作