学习代码提交预审查工具 pro-commit

介绍

Git 钩子脚本有助于在提交代码审查之前识别一些简单的问题。我们会在每次提交时运行钩子，自动指出代码中的问题，例如缺少分号、尾随空格以及调试语句。通过在代码审查之前指出这些问题，代码审查人员可以专注于变更的架构，而无需在琐碎的样式问题上浪费时间，且能统一风格与样式。

安装&部署
依赖

python=3.10.*

步骤
终端输入以下命令安装pre-commit

# 命令
pip install pre-commit

终端输入以下命令查看版本，响应输出版本号说明安装工具成功

# 命令
pre-commit --version
# 响应
pre-commit 4.2.0

仓库建立后，在相应的仓库目录下执行一下命令创建 .pre-commit-config.yaml配置项

# 命令1，生成.pre-commit-config.yaml
pre-commit sample-config > .pre-commit-config.yaml

# 查看.pre-commit-config.yaml文件内容
cat .pre-commit-config.yaml 
# 响应
# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.2.0
    hooks:
    -   id: trailing-whitespace
    -   id: end-of-file-fixer
    -   id: check-yaml
    -   id: check-added-large-files

Notes: 上述配置为基础配置，只执行4条基础规则，可根据实际项目需要对配置文件进行修改

基础规则：

id: trailing-whitespace
- 功能：移除文件中每行末尾的多余空格（ trailing whitespace ）。
- 作用：避免因无意的空格导致的代码差异，保持代码整洁。
id: end-of-file-fixer
- 功能：确保文件末尾以一个空行结束（符合大多数代码规范）。
- 作用：不同编辑器对文件结尾的处理可能不同，此钩子统一规范。
id: check-yaml
- 功能：检查 YAML 文件的语法是否正确（如缩进、格式错误）。
- 作用：避免提交无效的 YAML 配置文件（如 .github/workflows/*.yml、docker-compose.yml 等）。
id: check-added-large-files
- 功能：检查提交的文件是否超过指定大小（默认 50MB），防止大文件污染代码仓库。
- 作用：避免因大文件导致仓库体积膨胀，影响克隆 / 拉取效率

配置完成后，安装到仓库的.git 中，

# 命令
pre-commit install
# 响应
pre-commit installed at .git/hooks/pre-commit

安装完成后，将仓库内的变动一起提交到远程仓库即可；此时每次提交都会根据预设规则审查代码，若不符合代码规范则无法提交代码，此处提议与makefile一起使用，示例如下：
```
check:
        pre-commit run --files $(target)

commit:
        git add .
        git commit -m "$(msg)"

push: commit
        git push
```
为避免反复提交失败，提议在提交代码前进行本地检查，可以终端输入以下命令，

# 命令
pre-commit run --all-files

# 响应
[INFO] Initializing environment for https://github.com/pre-commit/pre-commit-hooks.
[INFO] Initializing environment for https://github.com/psf/black.
[INFO] Installing environment for https://github.com/pre-commit/pre-commit-hooks.
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
[INFO] Installing environment for https://github.com/psf/black.
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
Check Yaml...............................................................Passed
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Failed- hook id: trailing-whitespace- exit code: 1

Files were modified by this hook. Additional output:

Fixing sample.py

black....................................................................Passed

模板
python

# 全局默认配置
default_language_version:
    python: python3.9  # 指定默认 Python 版本（可写 "3.9" 或 "python3.9"）

minimum_pre_commit_version: 4.2.0   # 最低pro-commit 版本

files: .(py|json|yaml)$  # 只处理 Python/json/yaml 文件
exclude: ^(dist|build|.*exe$|.git/)  # 不处理 ./dist |./build | .exe结尾的所有对象 

# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.2.0
    hooks:
    -   id: trailing-whitespace  # 删除每行空白
    -   id: end-of-file-fixer    # 每个文件最后一行留白
    -   id: check-yaml           # 检测yaml格式
    -   id: check-added-large-files    # 检测是否有大文件提交 默认50MB

  - repo: https://github.com/psf/black  # Black 官方仓库
    rev: 24.4.2  # 使用的版本（提议选择最新稳定版，参考 https://github.com/psf/black/releases）
    hooks:
      - id: black  # 钩子 ID，对应 black 工具
        name: Format Python code with black  # 钩子名称（自定义，方便识别）
        language_version: python3.10  # 指定运行 black 的 Python 版本（需与项目兼容）
        args:  # 传递给 black 的参数
          - --line-length=120  # 自定义行宽（默认 88，根据团队习惯调整）
          # - --fast  # 可选：跳过 AST 一致性检查（加快速度，不推荐生产环境）

  # 2. Flake8：Python 代码检查工具（检测语法错误、风格问题等）
  - repo: https://github.com/PyCQA/flake8  # Flake8 官方仓库
    rev: 6.0.0  # 使用的版本（提议选择最新稳定版，参考 https://github.com/PyCQA/flake8/releases）
    hooks:
      - id: flake8  # 钩子 ID，对应 flake8 工具
        name: Lint Python code with flake8  # 钩子名称（自定义）
        args:  # 传递给 flake8 的参数
          - --max-line-length=120  # 行宽限制（需与 black 保持一致，避免冲突）
          - --ignore=E203,W503  # 忽略特定规则：
            # E203：与 black 格式冲突（black 允许冒号前的空格）
            # W503：与 black 冲突（black 允许逻辑运算符前换行）
          - --extend-ignore=F401  # 可选：忽略未使用的导入（如需严格检查可删除）
        additional_dependencies:  # 额外依赖（flake8 插件，扩展检查能力）
          - flake8-bugbear  # 增加更多代码质量检查规则（如反模式、最佳实践）
          - flake8-import-order  # 检查导入语句排序是否符合规范
  # 3. isort：自动排序 Python 导入语句
  - repo: https://github.com/PyCQA/isort  # isort 官方仓库
    rev: 5.13.2  # 使用最新稳定版本（参考 https://github.com/PyCQA/isort/releases）
    hooks:
      - id: isort  # 钩子 ID，对应 isort 工具
        name: Sort imports with isort  # 自定义钩子名称
        args:  # 传递给 isort 的参数
          - --profile=black  # 与 black 格式化工具兼容（避免格式冲突）
          - --line-length=120  # 行宽限制（需与 black、flake8 保持一致）
          - --multi_line=3  # 多行导入格式：3 表明垂直对齐（推荐与 black 配合）
          - --trailing-comma  # 多行导入末尾添加逗号（符合 black 风格）
        files: .py$  # 仅处理 Python 文件

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0  # 使用最新稳定版本
    hooks:
      - id: mypy
        name: mypy static type check
        args:
          # 核心检查模式
          - --strict  # 启用严格模式（可选，根据项目需求决定）
          - --show-error-codes  # 显示错误代码（如 [arg-type]）

          # 忽略缺失的导入（第三方库无类型注解时使用）
          - --ignore-missing-imports

          # 排除不需要检查的文件/目录（支持多个 --exclude）
          - --exclude=venv/  # 排除虚拟环境
          - --exclude=build/  # 排除构建目录
          - --exclude=tests/legacy/  # 排除旧测试代码

          # 放宽特定检查规则（仅在非严格模式下生效）
          # - --no-disallow-untyped-defs  # 允许未注解的函数
          # - --no-error-on-untyped-defs  # 不对未注解函数报错

          # 类型检查细节配置
          - --allow-redefinition  # 允许变量重定义（如在不同作用域）
          - --implicit-reexport  # 允许隐式导出（简化模块导入）

        # 仅检查 Python 文件
        files: .py$

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0  # 使用最新稳定版本
    hooks:
      - id: mypy
        name: mypy static type check
        args:
          # 核心检查模式
          - --strict  # 启用严格模式（可选，根据项目需求决定）
          - --show-error-codes  # 显示错误代码（如 [arg-type]）

          # 忽略缺失的导入（第三方库无类型注解时使用）
          - --ignore-missing-imports

          # 排除不需要检查的文件/目录（支持多个 --exclude）
          - --exclude=venv/  # 排除虚拟环境
          - --exclude=build/  # 排除构建目录
          - --exclude=tests/legacy/  # 排除旧测试代码

          # 放宽特定检查规则（仅在非严格模式下生效）
          # - --no-disallow-untyped-defs  # 允许未注解的函数
          # - --no-error-on-untyped-defs  # 不对未注解函数报错

          # 类型检查细节配置
          - --allow-redefinition  # 允许变量重定义（如在不同作用域）
          - --implicit-reexport  # 允许隐式导出（简化模块导入）

        # 仅检查 Python 文件
        files: .py$