当前位置：首页 > news >正文

pre-commit 的配置文件

news 2026/2/9 13:24:20

这个文件是 pre-commit 的配置文件，通常命名为 .pre-commit-config.yaml。pre-commit 是一个用于管理和维护多种预提交钩子的框架，旨在在代码提交（git commit）之前自动执行一系列检查和格式化任务，以确保代码质量和一致性。

文件用途

pre-commit 配置文件定义了一组钩子（hooks），这些钩子会在你执行 git commit 时自动运行。它们可以用于执行代码格式化、静态代码分析、检查潜在错误、确保代码风格一致等任务。通过使用 pre-commit，可以在代码进入版本库之前捕捉和修复问题，从而提高代码质量并减少代码审查中的问题。

使用方法

在文件顶部，有一些注释说明了如何使用和维护这个配置文件：

# 使用方法:
#
#     pre-commit run -a
#
# 或者:
#
#     pre-commit install  # (在每次使用 git commit 时自动运行)
#
# 更新此文件的方法:
#
#     pre-commit autoupdate
#
# 参考: https://github.com/pre-commit/pre-commit

具体步骤

安装 pre-commit

如果尚未安装 pre-commit，可以使用 pip 进行安装：
```
pip install pre-commit
```
安装 Git 钩子

在项目根目录下运行以下命令，将 pre-commit 钩子安装到 Git 中：
```
pre-commit install
```
这会确保每次执行 git commit 时，定义的钩子都会自动运行。
手动运行所有钩子

如果想手动运行配置文件中定义的所有钩子，可以使用：
```
pre-commit run -a
```
更新钩子版本

当需要更新配置文件中定义的钩子版本时，可以运行：
```
pre-commit autoupdate
```

文件内容解释

以下是文件的详细内容及其解释：

repos:# Standard hooks- repo: https://github.com/pre-commit/pre-commit-hooksrev: v3.4.0hooks:- id: check-added-large-files- id: check-case-conflict- id: check-merge-conflict- id: check-symlinks- id: check-xml- id: check-yaml- id: debug-statements- id: end-of-file-fixer- id: mixed-line-ending- id: trailing-whitespace- repo: https://github.com/psf/blackrev: 20.8b1hooks:- id: black- repo: localhooks:- id: clang-formatname: clang-formatdescription: Format files with ClangFormat.entry: clang-format-10language: systemfiles: \.(c|cc|cxx|cpp|frag|glsl|h|hpp|hxx|ih|ispc|ipp|java|js|m|proto|vert)$args: ['-fallback-style=none', '-i']- id: catkin_lintname: catkin_lintdescription: Check package.xml and cmake filesentry: catkin_lint .language: systemalways_run: truepass_filenames: false

1. `repos` 部分

repos 是一个列表，定义了多个仓库（repositories），每个仓库中包含了一组预定义的钩子。这些钩子可以来自第三方仓库，也可以是本地自定义的钩子。

a. 标准钩子仓库

- repo: https://github.com/pre-commit/pre-commit-hooksrev: v3.4.0hooks:- id: check-added-large-files- id: check-case-conflict- id: check-merge-conflict- id: check-symlinks- id: check-xml- id: check-yaml- id: debug-statements- id: end-of-file-fixer- id: mixed-line-ending- id: trailing-whitespace

repo: 指定钩子所在的仓库地址，这里使用的是 pre-commit 官方维护的标准钩子仓库。
rev: 指定仓库的版本标签或提交哈希，这里使用的是 v3.4.0 版本。
hooks: 列出具体要启用的钩子，每个钩子通过 id 指定。例如：
- check-added-large-files: 检查是否添加了过大的文件。
- check-case-conflict: 检查文件名大小写冲突。
- check-merge-conflict: 检查是否存在合并冲突标记。
- end-of-file-fixer: 确保文件以单个换行符结尾。
- trailing-whitespace: 检查并移除行尾空白。

b. Black 仓库

- repo: https://github.com/psf/blackrev: 20.8b1hooks:- id: black

repo: Black 是一个流行的 Python 代码格式化工具。
rev: 指定 Black 的版本，这里是 20.8b1 版本。
hooks: 启用 black 钩子，用于自动格式化 Python 代码。

c. 本地自定义钩子

- repo: localhooks:- id: clang-formatname: clang-formatdescription: Format files with ClangFormat.entry: clang-format-10language: systemfiles: \.(c|cc|cxx|cpp|frag|glsl|h|hpp|hxx|ih|ispc|ipp|java|js|m|proto|vert)$args: ['-fallback-style=none', '-i']- id: catkin_lintname: catkin_lintdescription: Check package.xml and cmake filesentry: catkin_lint .language: systemalways_run: truepass_filenames: false

repo: local: 表示这些钩子是本地自定义的，而不是来自远程仓库。
hooks:
- ClangFormat 钩子:
  - id: clang-format
  - name: 钩子的名称，便于识别。
  - description: 钩子的描述，说明其功能。
  - entry: 指定要执行的命令，这里是 clang-format-10，用于格式化代码。
  - language: 指定钩子所用的语言环境，这里使用 system，表示使用系统环境。
  - files: 正则表达式，匹配需要格式化的文件类型，如 .c, .cpp, .h 等。
  - args: 传递给 clang-format-10 的参数，这里设置了无回退风格并就地编辑文件。
- Catkin Lint 钩子:
  - id: catkin_lint
  - name: 钩子的名称。
  - description: 检查 package.xml 和 cmake 文件。
  - entry: 执行的命令，这里是 catkin_lint .，用于检查当前目录下的 Catkin 包。
  - language: 使用系统环境。
  - always_run: 设置为 true，表示无论文件是否变化，都要运行该钩子。
  - pass_filenames: 设置为 false，表示不传递文件名作为参数。

常见钩子功能详解

1. `pre-commit-hooks` 仓库中的钩子

check-added-large-files: 防止将过大的文件添加到版本库中。
check-case-conflict: 检查文件名的大小写冲突，避免在大小写不敏感的文件系统中出现问题。
check-merge-conflict: 检查文件中是否存在未解决的合并冲突标记。
check-symlinks: 检查符号链接的有效性。
check-xml: 验证 XML 文件的格式是否正确。
check-yaml: 验证 YAML 文件的格式是否正确。
debug-statements: 检查代码中是否包含调试语句（如 print、console.log 等）。
end-of-file-fixer: 确保文件以一个换行符结尾，并移除多余的换行符。
mixed-line-ending: 检查并报告文件中混合使用不同的行结束符（如 CRLF 和 LF）。
trailing-whitespace: 移除行尾的多余空白字符。

2. `black` 仓库中的钩子

black: 自动格式化 Python 代码，使其符合 Black 的代码风格规范。

3. 本地自定义钩子

clang-format: 使用 clang-format 工具自动格式化 C/C++ 等代码文件。
catkin_lint: 检查 ROS Catkin 包的 package.xml 和 CMake 文件，确保其配置正确。

总结

这个 pre-commit 配置文件通过定义多个钩子，帮助开发者在代码提交前自动执行一系列检查和格式化任务。这不仅提高了代码质量和一致性，还减少了代码审查中的常见问题。通过使用 pre-commit，团队可以确保所有提交的代码都符合预定义的标准和规范，从而提升整体开发效率和代码库的健康状况。

参考资源

Pre-commit 官方文档: https://github.com/pre-commit/pre-commit
Pre-commit Hooks 仓库: https://github.com/pre-commit/pre-commit-hooks
Black 代码格式化工具: https://github.com/psf/black
ClangFormat 工具: https://clang.llvm.org/docs/ClangFormat.html
Catkin Lint 工具: https://github.com/catkin/catkin_lint

通过理解和配置这些钩子，可以显著提升项目的代码质量和开发流程的自动化程度。