tomevault-io Git 工作流纪律
适用于：所有会改动代码的开发任务的完整生命周期。
0. 触发与跳过
TRIGGER：开始改动代码的工作 / 提到开分支 / 要求 commit / push / 开 PR / PR 合并后清理。 SKIP：纯咨询/阅读、极小打字纠错。
1. 分支策略
- 禁止在 main 直接提交
- 允许使用 git worktree，但工作树必须与当前 repo 物理隔离：放在仓库同级目录（如
../<repo>-<branch>）或集中到~/.worktree/下统一管理，禁止嵌套在当前 repo 工作目录内（避免污染主仓库、被误 add / commit）
开始任务前必查
git branch --show-current
- 在 main →
git pull→ 创建新分支 - 不在 main → 必须问用户：①基于当前分支继续/新开子分支 ②切回 main 后再开新分支。得到答复前不自行切换。
2. 阶段性本地 commit
- 每完成一个可独立验证的子任务 →
git commit（本地） - commit message 遵循仓库历史风格（先
git log --oneline -20看一眼） - 禁止阶段性 commit 后立即 push（本地未推时可 amend/rebase 修正）
- 任务队列还有待办 → commit 后直接继续，不中断询问
3. 推送门槛
仅当满足所有条件才进入推送：功能本地全部完成 + 所有测试通过 + 用户确认。
多 PR 依赖关系
有依赖 → 按顺序逐个 push + 开 PR，前一个合并后再推下一个。 无依赖 → 可并行推送，但仍需本地验证完成后统一开始。
4. PR 描述（六段式，整体 ≤ 50 行）
## 背景
当前状态、相关模块、为什么现在做。
## 需求
具体动因、要解决的问题、不做的代价。
## 方案
实际改动点、范围边界、影响面。
## 结果
改动后的行为变化、用户可感知的差异。
## 测试
验证方式、覆盖场景。
## 规范
遵循或涉及的规范（无 spec 时写"无"）。
reviewer 不跳转 issue 也能完整理解。禁止：只一行 What / 仅链接 issue / 仅粘贴 commit。
5. 按需建 issue（默认不建）
建的场景：跨多 PR 长周期追踪 / 暂不实施的 bug 记录 / 外部 triage。
issue 正文包含背景、需求、方案。PR 关联 issue 时顶部写 Closes #<num>。
6. 合并后清理
git checkout main && git pull origin main
git rev-parse --abbrev-ref HEAD # 确认在 main
git branch -D <branch> # squash merge 后 -d 会拒绝
# 探测远程分支是否存在再删
git ls-remote --exit-code --heads origin <branch> && git push origin --delete <branch>
git fetch -p # 裁剪远程引用
Source: 0xBB2B/bb-spec — distributed by TomeVault.