pre-commit - Git预提交钩子管理框架

pre-commit 是一个用于管理和维护多语言预提交钩子(pre-commit hooks)的框架。它可以帮助开发团队在代码提交前自动检查代码质量，确保代码风格一致，并防止常见错误进入代码库。

为什么需要pre-commit？

在团队协作开发中，保持代码风格一致和避免低级错误非常重要。传统的做法是：

依赖代码审查时人工发现这些问题
在CI流程中运行检查工具

但这两种方式都有明显缺点：

人工审查效率低且容易遗漏
CI流程发现问题时已经太晚，需要重新提交

pre-commit通过在代码提交前自动运行检查工具，可以：

提前发现问题，减少来回修改次数
统一团队代码风格
自动化执行重复性检查工作

核心特性

多语言支持：支持Python、Node.js、Ruby、Go等多种语言的工具
集中管理：通过配置文件统一管理所有钩子
隔离环境：每个钩子运行在独立环境中，避免依赖冲突
自动安装：自动下载和安装所需工具
快速执行：只检查变更的文件，运行速度快
跨平台：支持Linux、macOS和Windows

安装pre-commit

使用pip安装pre-commit：

1	pip install pre-commit

验证安装：

1	pre-commit --version

快速入门

1. 创建配置文件

在项目根目录创建.pre-commit-config.yaml文件，或使用以下命令生成示例配置：

1	pre-commit sample-config > .pre-commit-config.yaml

2. 示例配置

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
    -   id: check-yaml
    -   id: end-of-file-fixer
    -   id: trailing-whitespace
-   repo: https://github.com/psf/black
    rev: 23.10.1
    hooks:
    -   id: black
        args: [--line-length=88]

这个配置使用了两个仓库的钩子：

pre-commit-hooks：提供基础检查功能
black：Python代码格式化工具

3. 安装Git钩子

运行以下命令将pre-commit安装为Git钩子：

1	pre-commit install

现在，每次执行git commit时，pre-commit都会自动运行配置的钩子。

4. 手动运行所有文件

首次使用建议对所有文件运行检查：

1	pre-commit run --all-files

配置详解

pre-commit配置文件主要包含以下部分：

仓库(repos)

每个仓库代表一组钩子的来源，常用属性：

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0  # 指定版本或commit hash
    hooks:  # 该仓库下要使用的钩子列表
    -   id: check-yaml  # 钩子ID
        # 可选的钩子配置
        args: [...]  # 传递给钩子的参数
        files: \.yaml$  # 匹配的文件正则
        exclude: ^excluded/  # 排除的文件正则
        types: [yaml]  # 按文件类型过滤
        language_version: python3.8  # 指定语言版本

钩子(hooks)

每个钩子可以配置以下属性：

属性	说明
`id`	钩子的唯一标识符
`name`	显示名称(可选)
`entry`	覆盖默认入口点
`language`	钩子实现语言
`files`	匹配文件的正则表达式
`exclude`	排除文件的正则表达式
`types`	按文件类型过滤
`args`	传递给钩子的参数
`stages`	指定在哪个Git阶段运行

常用钩子推荐

基础检查

- repo: https://github.com/pre-commit/pre-commit-hooks
  rev: v4.4.0
  hooks:
    - id: check-yaml  # 检查YAML语法
    - id: end-of-file-fixer  # 确保文件以换行符结束
    - id: trailing-whitespace  # 删除行尾空格
    - id: check-added-large-files  # 防止提交大文件

Python项目

- repo: https://github.com/psf/black
  rev: 23.10.1
  hooks:
    - id: black  # 代码格式化

- repo: https://github.com/pycqa/isort
  rev: 5.12.0
  hooks:
    - id: isort  # 导入排序

- repo: https://github.com/PyCQA/flake8
  rev: 6.1.0
  hooks:
    - id: flake8  # 代码风格检查
      args: [--max-line-length=88]

# 添加 Ruff 钩子 (可替代 Black, isort, Flake8 等) 
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.4.4 # 请替换为最新的 Ruff 版本
  hooks:
    - id: ruff  # 运行代码检查 (linting)
      args: [--fix] # 自动修复检查出的问题
    - id: ruff-format # 运行代码格式化 (formatting)
      args: [--line-length=88] # 指定行长度

JavaScript项目

- repo: https://github.com/pre-commit/mirrors-eslint
  rev: v8.53.0
  hooks:
    - id: eslint
      additional_dependencies:
        - eslint@8.53.0
        - eslint-config-prettier@9.0.0

高级用法

本地钩子

对于项目特定的检查，可以创建本地钩子：

- repo: local
  hooks:
    - id: run-tests
      name: Run unit tests
      entry: pytest tests/
      language: system
      pass_filenames: false
      always_run: true

多阶段钩子

默认钩子在pre-commit阶段运行，也可以配置在其他Git阶段运行：

- repo: https://github.com/pre-commit/pre-commit-hooks
  rev: v4.4.0
  hooks:
    - id: check-large-files
      stages: [pre-push]  # 在git push时运行

自动更新

定期更新钩子版本：

1	pre-commit autoupdate

集成到CI/CD

在CI流程中也应该运行pre-commit检查：

# GitHub Actions示例
jobs:
  pre-commit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v3
      - run: pip install pre-commit
      - run: pre-commit run --all-files

最佳实践

团队统一配置：将.pre-commit-config.yaml纳入版本控制
渐进式采用：初期可以只启用基础检查
定期更新：使用pre-commit autoupdate保持工具最新
CI一致性：确保CI环境与本地使用相同的检查
性能考虑：将耗时检查放在CI阶段而非预提交阶段

总结

pre-commit是一个强大的Git预提交钩子管理工具，可以帮助团队：

自动化代码质量检查
统一代码风格
减少低级错误
提高开发效率

通过简单的配置，就可以为项目建立一套自动化的代码质量保障机制。

Git预提交工具pre-commit详解