pre-commit 用法

pre-commit 是 Git 钩子管理工具，在 git commit 前自动跑 lint/format/检查，让低级问题不进仓库。仓库根目录放一份 .pre-commit-config.yaml，团队成员 pre-commit install 即可统一规则。

三步上手

1. 安装

pip install pre-commit       # 推荐
brew install pre-commit      # macOS 备选
pre-commit --version

2. 写配置

项目根目录新建 .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             # YAML 语法检查
      - id: check-json             # JSON 语法检查
      - id: check-merge-conflict   # 检查未解决的合并冲突标记
      - id: debug-statements       # 阻止提交 print/breakpoint

3. 安装钩子

pre-commit install

完成。此后每次 git commit 都会先跑钩子，失败则阻断。

日常用法

命令	作用
git commit -m "..."	自动触发
pre-commit run --all-files	主动检查全部文件（CI / 首次接入推荐）
pre-commit run hook-id --all-files	单独运行某个钩子
git commit --no-verify	跳过检查（紧急专用，事后补做）
pre-commit autoupdate	升级所有钩子的 rev

常用钩子

Python

- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.5.0
  hooks:
    - id: ruff           # 极快的 lint
    - id: ruff-format    # 替代 black
 
- repo: https://github.com/pre-commit/mirrors-mypy
  rev: v1.10.0
  hooks:
    - id: mypy

JS/TS

- repo: https://github.com/pre-commit/mirrors-eslint
  rev: v9.2.0
  hooks:
    - id: eslint
 
- repo: https://github.com/pre-commit/mirrors-prettier
  rev: v3.2.5
  hooks:
    - id: prettier
      types_or: [javascript, typescript, css, html, markdown]

通用

- repo: https://github.com/codespell-project/codespell
  rev: v2.2.6
  hooks:
    - id: codespell
 
- repo: https://github.com/Yelp/detect-secrets
  rev: v1.4.0
  hooks:
    - id: detect-secrets

常见问题

现象	处理
钩子自动改了文件	重新 git add 修复后的文件再 commit
团队成员未启用	把 pre-commit install 加入 make setup 或 README 步骤
钩子版本陈旧	pre-commit autoupdate
想绕过	--no-verify 仅供紧急修复，且必须事后补检查

最佳实践

• 项目初期就引入，比后期统一风格成本低 10×
• 只装真正需要的钩子，过多钩子会拖慢开发体感
• 在 CI 中也跑 pre-commit run --all-files，防绕过本地
• 钩子规则的引入与变更要有团队共识