wandering1
295eb9911f
用户裁定 2026-10-28：慢钩子不再压在每个 git commit 上，由远端 CI 强制；本地等价入口 = scripts/ci_local.py 的 manual 段。 实测三根耗时：cppcheck 20.5 s、test-cppcheck 38.1 s、 test-coverage 105.2 s，合计 ~165 s ≈ 一次带代码提交耗时的 三分之二（test-coverage 的 files: 覆盖 App/，改一行就跑光 40 套）。 - .pre-commit-config.yaml：cppcheck / test-cppcheck / test-coverage 加 stages: [manual] + 理由注释；替换掉 test-coverage 上方「没写 stages → 所有阶段都跑、输出出现两次」 的旧坑注释（固定 manual 后不再有这一坑）。 - .gitea/workflows/ci.yml：static-gates job 在静态门禁步之后 新增「手动阶段门禁（覆盖率总闸 + 全量 cppcheck）」步， if: always()，逐根 --hook-stage manual（pre_commit run 不支持 多 id），日志 ci-artifacts/manual-stage.log + 归档 + STEP_SUMMARY， rc≠0 即失败；run 块纯 ASCII。 - scripts/ci_local.py：新增 MANUAL_STAGE_HOOKS 与 run_manual_stage() （静态段之后默认跑），删 run_coverage() 死代码，--coverage 降级为兼容别名。 - AGENTS.md + 12 篇 docs/scripts/README：三数同源口径改为 声明 51 / 提交期 --all-files 实跑 47 / +gitlint = 48， 其余 3 根在 manual 阶段；历史测量数字只加「当时」不回改。 验证：pre-commit run --all-files = 47 Passed / 0 Failed rc=0； manual 三根 Passed（test-coverage line 89.8% func 93.2% 41/41 套）； ci_local.py --static-only 全绿；check_doc_links --all --sections-strict rc=0、mojibake / bom-drift / id-check-new rc=0； ci.yml yaml.safe_load 通过。未改任何 .c/.h，故未跑 @build。
3.8 KiB
3.8 KiB
gitlint — 提交信息格式（commit-msg 阶段）
一句话：管提交信息长什么样：标题长度、正文行长度。内容真假、是否与 diff 相符，它一个字都不评。
- 配置：官方
gitlintv0.19.1（repo: https://github.com/jorisroovers/gitlint），规则文件.gitlint：ignore=body-is-missing、[title-max-length] line-length=100，其余用默认值。 - 阶段：只在
commit-msg跑（.pre-commit-config.yaml顶部default_install_hook_types:显式装了commit-msg）。
1. 它在查什么（本仓实际生效值）
| 项 | 生效值 | 来源 |
|---|---|---|
| 标题最大长度 | 100 字符 | .gitlint 覆盖默认 |
| 正文每行最大长度 | 79/80 字符级（gitlint 默认 max-line-length） |
gitlint 默认 |
| 正文缺失 | 不检查 | .gitlint 显式 ignore |
标题结尾标点等 T 系列 |
默认 | gitlint 默认 |
2. 为什么要它
- 本仓的提交说明是主要载体：实测数据、基线只减不增的口径、负结果、为什么这么改，全写在正文
里。格式一炸（超长行在
git log/ 网页里被硬切），这些内容就没人读得下去。 - 两条本仓真踩过的坑，已固化进
AGENTS.md： ① 中文长标题极易超 100 → 标题保持短，细节写正文； ② 正文每行必须控制在 80 内，而且用git commit -m传长中文会被终端代码页转码破坏 → 一律"短标题 +git commit -F <UTF-8 无 BOM 文件>"。
3. 触发面 / 看不见什么
git commit、--amend、-F、合并生成的提交都会跑；--no-verify连它和其它 47 个pre-commit阶段钩子一起跳过（stages: [manual]的三根慢钩子（cppcheck/test-cppcheck/test-coverage）本来就不随提交跑，不受影响）。- 不校验：提交说明与 diff 是否相符、是否真的构建/测试过、是否夹带无关改动、是否该拆成多笔。
4. 报错怎么读
gitlint..............................................................Failed
12: BBody line length limit exceeded, lengthy body line (max-line-length: 79)
1: Title has trailing whitespace
-
前缀数字是行号（第 1 行是标题）。本仓最常犯的是
B（正文行超长）与标题超 100。 -
稳妥写法：正文落成 UTF-8 无 BOM、每行 ≤78 字符的临时文件，再
git commit -F；提交前自查 有没有超 80 的行（本目录作者在实践中就是先做这一步再提交）。 -
典型报错（本仓最常撞的两条）：标题超长（例：159 > 100）、正文单行超长（例：87 > 80）。
-
口径是宽松：不强制 Conventional Commits、兼容中文标题；配置源是仓库根
.gitlint， 不是 hook args（改规则去改那个文件，不是在 yaml 里加 args）。
5. 好处
git log在任何终端宽度都可读；长说明（含实测数字与踩坑）能完整留在历史里，这是本仓历史 可读性的基础设施。
6. 限制与盲区
body-is-missing被显式忽略 → 空说明也能过。信息质量完全靠自觉（本仓选择宽松，代价写在这里）。- 只管格式：正文写满 40 行错误结论也照样过。
- 不追溯历史：
--no-verify用多了，历史里就永远留着不合规提交，事后无法自动补齐。 - 长度按字符数算，不是显示宽度：中英文混排 + 反引号时，"看着没到 80"仍可能超限。
- 它不看提交是否该拆（一次提交里混了代码 + 文档 + 配图，它不管）。
7. 豁免与基线 / 8. 改这个门禁本身
- 无基线；放宽只能改
.gitlint。抬长度前先确认你要的不是"把长句拆短"。 - 想加严（例如要求正文非空、要求带模块前缀）：先在最近 20 条真实提交上试跑，别直接关闸。