C++ 项目中使用 Pre-commit 协助实现代码规范检查

0. 前言

• 多人项目开发需要统一代码规范，为了执行这些代码规范，需要有工具的辅助。
• 目前选择的工具组合式：
  • precommit：在执行 git commit 的时候进行代码检查。具体执行的命令就是通过下面几个工具。
  • clang-format：代码格式检查（formatting工具，只检查格式）
  • cpplint：C++代码静态检查工具

1. 工具简单介绍

1.1 pre-commit 的简单使用

• 官网
• 第一步：安装，pip install pre-commit
• 第二步：在项目根目录下添加配置文件 .pre-commit-config.yaml ，示例如下。
  • 需要注意的是 repo 的链接。pre-commit 会执行 git clone 命令，如果是 gitlab/github 的很可能在服务器上无法正常获取。
  • 在官方 Hook 列表中选择了 pocc/pre-commit-hooks，这个库中带有我们目前所有的工具（还有更多）。

fail_fast: false
repos:
  - repo: https://github.com/pocc/pre-commit-hooks
    rev: master
    hooks:
      - id: clang-format
        args: [--style=Google]
      - id: clang-tidy
      - id: oclint
      - id: uncrustify
      - id: cppcheck
      - id: cpplint
      - id: include-what-you-use

• 第三步：根据配置文件安装hook，即在项目根目录下运行 pre-commit install
  • 注意，git hook 是 git 本身自带的功能，而不是 pre-commit 提供的，而pre-commit 实现的就是注册了一些 git 能够使用的 hook。
• 第四步：在当前项目执行 git commit 时会自动进行代码检查。
  • 注意：git clone 命令应该是在此时执行，如果网速不够会失败。
  • 所有repo只需要clone一次，但我也没具体了解过clone到哪里。

1.2 clang-format

• clang-format 是 Clang 编译器中的一个工具，是 C++ 代码 formatting（格式化）的最常用工具。

• 安装：

  • ubuntu 下 apt install clang-format 就行
  • 如果是使用 pre-commit 工具，需要先安装

• 文档：

  • clang-format命令文档
  • clang-format配置文件文档

• 构建配置文件 .clang-format

  • 目前我只用到指定Google规范，其他的都无所谓。

BasedOnStyle: Google

1.3 cpplint

• Google 出品的静态代码检查工具

  • 官方Github路径
  • 非官方维护，但现在常用的 Github cpplint/cpplint

• 安装：

  • 直接通过 pip install cpplint 即可
  • 如果是通过 pre-commit 工具，需要先安装

• 文档：要么直接看源码中的注释，要么通过 cpplint -h 来查看

• 参数设置：如果需要设置参数，可以在 precommit 的配置文件中指定

• 命令示例

cpplint --verbose=0 \
	--recursive \
	--exclude=build/* \
	--exclude=3rdparty/* \
	.

2. 最佳实践

• 方便自己后续使用，记录一下。
• 目标：部署 pre-commit 的 C++ Code Review 环境。
• 步骤：
  • 准备配置文件。
  • 安装指定程序以及 git hook。

2.1 配置文件

• 在项目根目录下新建名为 .pre-commit-config.yaml 的文件，内容如下
  • 注意，原始 repo 路径为 https://github.com/pocc/pre-commit-hooks，但由于公司连Github网速太慢，所以在公司git上上传了一份代码，然后使用公司内部的链接。同理，如果连Github网速慢，也可以放到gitee上。

repos:
  - repo: https://git.cethik.com/zhangyiyang/cpp-pre-commit-hooks.git
    rev: master
    hooks:
      - id: clang-format
        args: [--style=Google]
      - id: cpplint

2.2 安装依赖程序

• 主要就是安装 pre-commit/clang-format/cpplint

• Ubuntu 下安装与使用

sudo apt install cpplint
pip3 install pre-commit cpplint
pre-commit install