完善pre-commit使用说明：补充cppcheck详解，更新no-mojibake状态
This commit is contained in:
+64
-36
@@ -86,29 +86,73 @@ git commit
|
||||
|
||||
### 2.6 cppcheck — C 静态分析
|
||||
|
||||
| 项 | 说明 |
|
||||
cppcheck 是开源 C/C++ 静态分析工具，**不运行代码**，通过语法分析和数据流推理发现潜在缺陷。
|
||||
|
||||
**工作原理**：逐个读取 C 文件 → 分析语法/数据流/控制流 → 发现问题则报错。
|
||||
|
||||
#### 本项目开启的检查类别
|
||||
|
||||
| 类别 | 含义 | 典型问题 |
|
||||
|---|---|---|
|
||||
| `warning` | 通用警告 | 变量未使用、除零风险、空指针解引用、 unreachable code |
|
||||
| `performance` | 性能问题 | 不必要的值拷贝、字符串重复查找、低效的函数调用 |
|
||||
| `portability` | 可移植性问题 | 不同平台行为不一致的代码、隐式类型转换 |
|
||||
|
||||
#### 不开启的常见类别
|
||||
|
||||
| 类别 | 为什么不开 |
|
||||
|---|---|
|
||||
| **触发条件** | C 文件含 warning / performance / portability 级别缺陷 |
|
||||
| **处理方式** | **阻止提交** |
|
||||
| **扫描范围** | `App/`、`Src/`、`Inc/`、`Drivers/BSP/` 下的 .c 文件（排除第三方库） |
|
||||
| **已知抑制** | `missingInclude`、`invalidPrintfArgType_sint/uint`（项目安全使用，非真正缺陷） |
|
||||
| **典型报错** | `path/to/file.c:42: warning: ...` |
|
||||
| **修复方式** | 根据 cppcheck 报告修复代码缺陷；若为误报可在 `.pre-commit-config.yaml` 的 args 中添加 `--suppress=规则名` |
|
||||
| `style` | 太多噪音（未使用函数、未用参数），会淹没真正问题 |
|
||||
| `error` | 严重错误（数组越界、内存泄漏），cppcheck 默认已包含，不需要显式加 |
|
||||
| `information` | 信息类（未解析的头文件等），无实际价值 |
|
||||
|
||||
**排除目录**（不参与 cppcheck 扫描）：
|
||||
#### 配置参数说明
|
||||
|
||||
```
|
||||
Drivers/CMSIS/ # ARM CMSIS（第三方）
|
||||
Drivers/STM32F4xx_HAL_Driver/ # ST HAL（第三方）
|
||||
Drivers/BSP/UI/ # LVGL UI 层（第三方）
|
||||
Drivers/BSP/NET/lftpd/ # LwIP FTP（第三方）
|
||||
Drivers/BSP/dhara/ # NAND FTL（第三方）
|
||||
Lib/ # LVGL 库
|
||||
Middlewares/ # FreeRTOS
|
||||
MDK-ARM/ # Keil 工程文件
|
||||
test/ # 测试代码
|
||||
--std=c99 # 按 C99 标准检查（Keil 工程常用）
|
||||
--error-exitcode=1 # 发现问题返回非零退出码（pre-commit 用来拦截提交）
|
||||
--quiet # 只报问题，不显示扫描进度
|
||||
--suppress=missingInclude # 抑制"找不到头文件"（HAL/CMSIS 路径在 Keil 工程配置里，cppcheck 不知道）
|
||||
--suppress=invalidPrintfArgType_sint # printf 的 %d 传 uint32_t —— 实际安全，非真正缺陷
|
||||
--suppress=invalidPrintfArgType_uint # printf 的 %u 传 int —— 实际安全，非真正缺陷
|
||||
-I Inc -I App -I Drivers/BSP # 指定头文件搜索路径，让 cppcheck 能解析 #include
|
||||
```
|
||||
|
||||
#### 扫描范围
|
||||
|
||||
通过 `types: [c]` + `exclude` 控制：
|
||||
|
||||
**检查**：`App/`、`Src/`、`Inc/`、`Drivers/BSP/` 下的 .c 文件
|
||||
|
||||
**不检查**（第三方库，问题不是我们的）：
|
||||
|
||||
```
|
||||
Drivers/CMSIS/ # ARM CMSIS
|
||||
Drivers/STM32F4xx_HAL_Driver/ # ST HAL
|
||||
Drivers/BSP/UI/ # LVGL UI 层
|
||||
Drivers/BSP/NET/lftpd/ # LwIP FTP
|
||||
Drivers/BSP/dhara/ # NAND FTL
|
||||
Lib/ # LVGL 库
|
||||
Middlewares/ # FreeRTOS
|
||||
MDK-ARM/ # Keil 工程文件
|
||||
test/ # 测试代码
|
||||
```
|
||||
|
||||
#### 如何抑制误报
|
||||
|
||||
如果 cppcheck 对某段代码报了误报，在 `.pre-commit-config.yaml` 的 cppcheck `args` 中添加：
|
||||
|
||||
```yaml
|
||||
args: [--suppress=规则名, ...]
|
||||
```
|
||||
|
||||
常用可抑制规则：`uninitvar`（未初始化变量，但你确定后续会赋值）、`knownConditionTrueFalse`（条件恒真/假，但你故意这么写）。
|
||||
|
||||
#### 日常速度
|
||||
|
||||
- **增量扫描**（`git commit` 时）：只检查 staged 文件，通常 <1 秒
|
||||
- **全库扫描**（`pre-commit run --all-files`）：约30秒，仅在配置变更后使用
|
||||
|
||||
### 2.7 no-mojibake — U+FFFD 乱码拦截
|
||||
|
||||
| 项 | 说明 |
|
||||
@@ -117,15 +161,9 @@ test/ # 测试代码
|
||||
| **处理方式** | **阻止提交**（不可逆，必须修复） |
|
||||
| **检测原理** | `scripts/check_mojibake.py` 以二进制读取文件，检测 `0xEF 0xBF 0xBD` 字节序列 |
|
||||
| **典型报错** | `U+FFFD replacement chars found (encoding corrupted, irreversible!): path/to/file.c` |
|
||||
| **修复方式** | 从 git 历史中找到最后一个干净版本（`git log` + `git show HEAD~N:path/to/file.c > file.c`），手动恢复损坏区域 |
|
||||
| **修复方式** | 从 git 历史中找到最后一个干净版本，手动恢复损坏区域 |
|
||||
|
||||
**已知豁免**（`exclude` 配置）：
|
||||
|
||||
```
|
||||
Drivers/BSP/TPAFE5160/tpafe5160.c # 历史遗留乱码，待修复后取消豁免
|
||||
```
|
||||
|
||||
> ⚠️ **编码铁律**：U+FFFD 是不可逆损坏。若发现新文件出现 U+FFFD，必须排查写入方式（禁用 Get-Content / Set-Content 重写中文文件）。
|
||||
> ⚠️ **编码铁律**：U+FFFD 是不可逆损坏（无法从替换符反推原始中文字符）。若发现新文件出现 U+FFFD，必须排查写入方式（禁用 Get-Content / Set-Content 重写中文文件）。
|
||||
|
||||
### 2.8 gitlint — Commit Message 格式
|
||||
|
||||
@@ -237,16 +275,6 @@ pre-commit run --all-files
|
||||
$env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")
|
||||
```
|
||||
|
||||
### 5.2 tpafe5160.c 乱码
|
||||
|
||||
**状态**：已知历史遗留，HEAD（`e06d849`）已含 131 处 U+FFFD。no-mojibake 钩子已豁免该文件。
|
||||
|
||||
**修复计划**：从 `fe107ea`（干净版本）恢复注释区，完成后取消 `.pre-commit-config.yaml` 中的 `exclude` 条目。
|
||||
|
||||
### 5.3 LVGL 文档移动未提交
|
||||
|
||||
**状态**：工作区有 `docs/测试说明/LVGL模拟器部署与使用说明.md` 的删除（D）和 `docs/LVGL模拟器部署与使用说明.md` 的未跟踪（??），为用户历史操作，不在 pre-commit 管理范围内。
|
||||
|
||||
### 5.4 clang-format 未启用
|
||||
|
||||
**原因**：全库 222 个 .c/.h 文件大概率不满足 clang-format 默认格式，启用后会批量重写。
|
||||
@@ -263,7 +291,7 @@ $env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Env
|
||||
| `.gitlint` | 仓库根 | gitlint 规则（宽松，兼容中文） |
|
||||
| `scripts/check_mojibake.py` | scripts/ | U+FFFD 检测脚本 |
|
||||
| `docs/自动化代码审查实施.md` | docs/ | 实施规划文档（Route A/B 设计） |
|
||||
| `docs/测试说明/pre-commit使用说明.md` | 本文档 | 部署与使用说明 |
|
||||
| `docs/pre-commit使用说明.md` | 本文档 | 部署与使用说明 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user