pre-commit 的配置文件

这个文件是 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

具体步骤

1. 安装 pre-commit

   如果尚未安装 pre-commit，可以使用 pip 进行安装：

   pip install pre-commit

2. 安装 Git 钩子

   在项目根目录下运行以下命令，将 pre-commit 钩子安装到 Git 中：

   pre-commit install

   这会确保每次执行 git commit 时，定义的钩子都会自动运行。

3. 手动运行所有钩子

   如果想手动运行配置文件中定义的所有钩子，可以使用：

   pre-commit run -a

4. 更新钩子版本

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

   pre-commit autoupdate

文件内容解释

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

repos:
  # Standard hooks
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.4.0
    hooks:
      - 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/black
    rev: 20.8b1
    hooks:
      - id: black

  - repo: local
    hooks:
      - id: clang-format
        name: clang-format
        description: Format files with ClangFormat.
        entry: clang-format-10
        language: system
        files: \.(c|cc|cxx|cpp|frag|glsl|h|hpp|hxx|ih|ispc|ipp|java|js|m|proto|vert)$
        args: ['-fallback-style=none', '-i']
      - id: catkin_lint
        name: catkin_lint
        description: Check package.xml and cmake files
        entry: catkin_lint .
        language: system
        always_run: true
        pass_filenames: false

1. repos 部分

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

a. 标准钩子仓库

- repo: https://github.com/pre-commit/pre-commit-hooks
  rev: v3.4.0
  hooks:
    - 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/black
  rev: 20.8b1
  hooks:
    - id: black

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

c. 本地自定义钩子

- repo: local
  hooks:
    - id: clang-format
      name: clang-format
      description: Format files with ClangFormat.
      entry: clang-format-10
      language: system
      files: \.(c|cc|cxx|cpp|frag|glsl|h|hpp|hxx|ih|ispc|ipp|java|js|m|proto|vert)$
      args: ['-fallback-style=none', '-i']
    - id: catkin_lint
      name: catkin_lint
      description: Check package.xml and cmake files
      entry: catkin_lint .
      language: system
      always_run: true
      pass_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

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