一键规范代码：pre-commit自动化检查工具实战指南

拒绝脏代码污染仓库，用自动化守护代码质量

本文来自「大千AI助手」技术实战系列，专注用真话讲技术，拒绝过度包装。

简介

• • pre-commit工具提供git提交(git commit)前自动运行的任务(例如代码检查或格式化等任务)

  往期文章推荐:

• 20.Python3安装MySQL-python踩坑实录：从报错到完美解决的实战指南
• 19.Git可视化革命：3分钟学会用Mermaid+AI画专业分支图
• 18.vscode常用快捷命令和插件
• 17.AI制图新纪元：3分钟用Mermaid画出专业类图
• 16.3分钟搞定数据可视化：Mermaid饼图终极指南
• 15.5分钟玩转Swagger UI：Docker部署+静态化实战
• 14.记录下blog的成长过程
• 13.再说一说LangChain Runnable接口
• 12.Docker实战：5分钟搞定MySQL容器化部署与最佳实践
• 11.Ollama模板全解析：从基础语法到高级应用实战
• 10.Ollama完全指南：从零开始玩转本地大模型部署
• 9.django中如何解析content-type=application/json的请求
• 8.实测DeepSeek分词机制：你的输入如何变成计费Token？
• 7.英语分词进化论：BPE相关论文汇总
• 6.硬核实战 | 3分钟Docker部署ClickHouse列存数据库
• 5.技术深解 | DeepSeek-R1-0528训练参数全透视：163K上下文与MoE高效架构的基石
• 4.DeepSeek最新升级实测：推理能力翻倍，但离世界顶尖还有多远？
• 3.血泪教训！Redis默认配置竟会导致数据丢失？Docker生产部署指南
• 2.Function Call：大模型如何突破自身局限“使用工具“
• 1.DeepSeek动手实践：创建一个自动连点器

使用

四步上手

• • Step1.安装pre-commit
  • • 命令 - pip install pre-commit
• • Step2.添加pre-commit配置
  • • 在项目根目录创建配置文件.pre-commit-config.yaml并配置相关项
    • • 也可以通过pre-commit sample-config生成基本配置示例
• • Step3.安装配置的hooks
  • • 命令 - pre-commit install
    • • 每次clone一个新的项目都要运行一次pre-commit install安装
• • Step4.对所有文件执行
  • • 命令 - pre-commit run --all-files
    • • ⚠️ 注意：日常提交时仅检查变更文件(增量检查)，此步骤用于全量初始化
  • • 一般修改hooks的时候都会对所有文件执行一次检查

进阶命令

• • 通用
  • • 是否在输出时带颜色 - --color {auto,always,never}
    • • 默认auto
  • • 指定特定的配置文件(而非默认的) - -c, --config CONFIG
• • 安装hooks时(pre-commit install [options])
  • • 替换已存在的git hooks - -f, --overwrite
  • • 是否安装hooks的时候同时安装hooks的运行环境(默认首次运行时安装) - --install-hooks
  • • 安装指定的hook - -t, --hook-type HOOK_TYPE
• • 运行hook时(pre-commit run [hook-id] [options])
  • • 仅运行指定的hook - [hook-id]
  • • 是否在仓库中的所有文件上运行 - -a, --all-files
  • • 仅在指定的文件上运行 - --files [FILES [FILES ...]]
  • • 仅在指定的提交(git commit hash)范围内修改的文件上运行 - --from-ref FROM_REF --to-ref TO_REF
  • • 设置运行的stage(满足该stage的hook才会被运行) - --hook-stage STAGE

配置

配置文件

• • 配置文件为项目根目录的.pre-commit-config.yaml

配置格式

• • 核心配置格式和常见选项

files: <正则匹配> # 可选,对哪些文件有效(匹配文件的正则表达式),全局(默认'')
exclude: <正则>  # 可选,对哪些文件无效(排除文件的正则),全局(默认^$)
default_stages: [commit]   # 可选,触发阶段(默认all stages)只对没有设置stages的hooks有效
fail_fast:  # 可选,是否在首次失败后就停止pre-commit的运行(默认false)
repos:
  - repo: <仓库URL>       # 钩子工具的源码仓库地址(Github/Gitlab等的URL)(git clone用)或者local或meta
    rev: <版本/标签>      # 使用的哪个版本（如 tag、commit hash），在repo是url的时候才能有该参数
    hooks:                # 定义具体执行的钩子任务列表(每个hook通过id唯一标识)
      - id: <钩子ID>      # 必填,使用哪个hook,hook工具的唯一标识(不同的仓库repo都有支持的hook的列表)
        name: <显示名称>  # 可选,自定义的工具执行时显示的名称(repo=local的hook则必填)
        args: [...]       # 可选,传递给钩子的参数
        entry: ...     # 可选,入口点(要运行的可执行文件)(可以包含参数)(比如 autopep8 -i)(repo=local则必填)
        files: <正则匹配> # 可选,对哪些文件有效(匹配文件的正则表达式)
        exclude: <正则>  # 可选,对哪些文件无效(排除文件的正则)
        types: [file_type] # 可选,对哪些文件类型的文件有效(如 directory, file, symlink, executable, text, binary等)(可通过identify-cli xxx查看xxx文件的类型)
        exclude_types: [file_type] # 可选,排除的文件类型
        stages: [commit]   # 可选,触发当前hook执行的阶段(默认commit, 还支持 push 等)
        language: <语言>  # 可选,工具的运行环境(如system: 系统已安装的命令、python: Python环境、node: node.js环境、docker: docker容器)(repo=local则必填)
        pass_filenames: [true/false] # 是否传递要处理的文件的文件名作为参数(默认true)

常用工具

• • pre-commit官方提供的hooks仓库为https://github.com/pre-commit/pre-commit-hooks
  • • 常用hooks有(作为id标识)
    • • 文件名
      • • check-case-conflict - 检查文件名是否可能存在大小写冲突
      • • check-illegal-windows-names - 检查不能在windows上创建的文件
    • • 文件格式
      • • check-ast - 检查文件是否是正常的Python语法
      • • check-json - 检查json文件并验证语法
      • • check-toml - 检查TOML文件并验证语法
      • • check-xml - 检查XML文件并验证语法
      • • check-yaml - 检查YAML文件并验证语法
    • • 文件大小
      • • check-added-large-files - 检查提交的大文件
    • • 符号链接
      • • check-symlinks - 检查符号链接
      • • destroyed-symlinks - 符号链接
    • • 安全
      • • detect-private-key - 是否存在私钥
    • • 格式化
      • • check-docstring-first - 检查docstring是否在代码前
      • • double-quote-string-fixer - 替换双引号字符串为单引号字符串
      • • end-of-file-fixer - 文件末尾空行
      • • trailing-whitespace - 移除末尾空白符
    • • 测试
      • • name-tests-test - 测试文件命名是否正确
• • black官方提供的hooks仓库为https://github.com/psf/black
  • • 常用hooks有
    • • black - 运行black命令进行Python代码格式化
• • 本地hooks为 local
  • • 可直接在entry里写要执行的命令

参考

• • hooks - https://github.com/pre-commit/pre-commit-hooks
• • pre-commit - https://pre-commit.com/#plugins
• • 其他常用hooks - https://pre-commit.com/hooks.html
• • https://github.com/pandas-dev/pandas/blob/main/.pre-commit-config.yaml
• • https://github.com/Significant-Gravitas/AutoGPT/blob/master/.pre-commit-config.yaml

本文由「大千AI助手」原创发布，专注用真话讲AI，回归技术本质。拒绝神话或妖魔化。搜索「大千AI助手」关注我，一起撕掉过度包装，学习真实的AI技术！