Git — 版本控制工作流

入口/出口

• 入口: build 过程中需要提交代码或创建分支
• 出口: 整洁、可分拆审查的提交历史
• 指向: 继续 build 或进入 verify-workflow-review
• 前置加载: CANON.md
• 输出路径: 提交历史 → verify-workflow-review 审查

何时不使用

• 只是读取历史、查看状态或解释 Git 概念，不创建提交/分支
• 当前任务明确要求不要提交或不要改动版本历史
• 需要清理未归属改动但无法判断来源时，先询问 human partner

Iron Law

<HARD-GATE>

原子提交、描述性信息、关注点分离。
绝不 `git add -A`、绝不 force-push 共享分支、绝不跳过钩子、绝不提交密钥。
每个提交是独立可理解、可 revert、可 bisect 的。

</HARD-GATE>

核心原则

1. Trunk-Based Development（推荐）

main ────○────○────────○────○── (经常合并小改动)
           \          /
feature     ○──○──○──○  (短生命周期分支，< 2 天)

规则:

• 分支存活 < 2 天
• 合并前 rebase 到最新 main
• 小 PR（100-300 行）> 大 PR
• 直接提交到 main 仅用于文档修复、配置调整等无行为变更

2. 原子提交 — 一个改动一个提交

Good:
  1a2b3c feat: add Task.create() with validation
  4d5e6f test: add unit tests for Task.create()
  7f8g9h refactor: extract validateTask to shared module

Bad:
  abc123 feat: add task creation, tests, refactor validation, fix typo in README

每个提交是独立可理解、可 revert、可 bisect 的。

3. 描述性提交信息

<type>: <简短摘要（< 50 字符）>

<详细说明 —— 为什么改，不是什么（可选，如有必要）>

类型: feat / fix / refactor / test / docs / chore / perf / security

提交信息写 why，不是 what。git diff 已经显示了 what。

Good:
  fix: prevent race condition when two users complete same task
  
  The task status check and update were not atomic, allowing two
  concurrent requests to both mark a task as completed.

Bad:
  fix: update task service

4. 关注点分离

• 格式化变更 → 单独的格式化提交
• 重命名/移动文件 → 单独提交（不要混入行为变更）
• 行为变更 → 单独的提交

绝不将格式化变更和行为变更混在一次提交。

5. 变更大小

目标: 每次提交约 100 行。 超过 300 行 → 执行是否拆分。

Save Point 模式

频繁提交、经常 push。提交 = 保存点，不是最终成品。

实现 Task A      实现 Task B      格式化          Rebase 到 main
    │                │               │                  │
    ▼                ▼               ▼                  ▼
commit + push   commit + push   commit + push    git pull --rebase
                                                    │
                                               push + merge

安全网: 每完成一个逻辑单元（一个函数、一个测试、一个重构步骤）就 commit。如果之后搞砸了，回退成本低。

Worktree 隔离

为不相关的工作创建隔离环境：

# 创建隔离工作区
git worktree add -b feature/x ../project-feature-x main

# 在隔离区工作
cd ../project-feature-x

# 完成 → 合并 → 清理
git worktree remove ../project-feature-x

何时用 worktree:

• 同时处理多个不相关的任务
• 需要快速切回 main 验证某个行为而不丢失当前进度
• 运行长时间脚本（测试、构建）时不阻塞

Pre-Commit Hygiene

提交前检查：

git diff --staged            # 审查你实际要提交的变更
git diff --staged --check    # 检查空白字符错误
npm test                     # 运行测试（如果项目有预提交钩子则自动）

绝不:

• git add -A 或 git add . — 手动选择文件，避免误提交密钥、二进制文件
• git push --force 到共享分支 — 改写了别人的基准
• --no-verify 跳过钩子 — 除非钩子坏了且有充分理由
• 提交 .env、credentials.json、node_modules、编译产物

Git 调试工具

git bisect start HEAD <known-good-commit>  # 二分查找引入 bug 的提交
git log -- path/to/file                    # 看文件变更历史
git blame -L 10,30 path/to/file            # 看特定行是谁改的
git grep "pattern" $(git rev-list --all)   # 在所有提交中搜索

常见说辞

红旗 — STOP

<HARD-GATE> 以下任何一个出现，立即停止提交：

• staged 文件超过 10 个且不属于同一改动
• 提交信息 = "fix"、"update"、"WIP"（信息量为零）
• git add -A 把不相关的文件一起 staged
• 分支存活超过 3 天且差异超过 500 行
• 格式化变更和行为变更出现在同一 staged 中
• force-push 到 main/master（重写共享历史）
• staged 中包含 .env 或密钥文件
• 合并冲突时用 --theirs 整块解决而不是逐一检查

</HARD-GATE>

验证清单

• 每个提交是单一逻辑单元
• 提交信息使用 <type>: <summary> 格式，解释了 why
• 变更按关注点分离（格式化 vs 行为 vs 重命名）
• 没有误提交的密钥、二进制文件或生成文件
• 分支基于最新 main/master
• 测试在提交前通过
• 没有 force-push 到共享分支

验证失败处理

好坏示例

Good — 原子提交序列

1a2b3c feat: add Task.create() with validation
4d5e6f test: add unit tests for Task.create()
7f8g9h refactor: extract validateTask to shared module

→ 每个提交单一逻辑单元，可独立 revert，可 bisect 定位

Bad — 巨型混合提交

abc123 feat: add task creation, tests, refactor validation, fix typo in README

→ 问题: 4 个改动混在一起 → revert 任务创建时被迫也 revert 测试、重构和 typo 修复 → 问题: bisect 定位 bug 时无法缩小范围 → 调试时间 5-10x

输出模板

提交序列应遵循以下格式（每提交检查）：

## Commit Checklist
- [ ] 提交类型: feat/fix/refactor/test/docs/chore/perf/security
- [ ] 提交摘要 < 50 字符，描述 why
- [ ] 变更行数 < 300（超过需拆分）
- [ ] 格式化/重命名/行为变更已分离
- [ ] 无密钥、二进制、生成文件误提交
- [ ] 测试在提交前已通过