用途:把“ship it”拆成有纪律的交付生命周期——暂存、提交、推送、开 PR,并闭环处理评审意见与 CI 失败,避免 add -A 误提交密钥、无意义的提交信息、缺少验证步骤的 PR 等问题。
主要能力与用法:
- 先确认仓库流程。提交前检查 CONTRIBUTING.md、AGENTS.md、PR 模板或 CI 配置;若规定了分支命名、提交信息规范(如 Conventional Commits、sign-off、issue 前缀)或 PR 必填段落,应优先遵循。仅当用户要求时才提交或推送,且绝不直接推送到默认分支。
- 暂存。先读 git status 和 git diff,再按文件名暂存(git add path/...),不要用 git add -A 或 git add .;暂存后运行 git diff --cached 完整阅读。混入两件无关的事应拆成两次提交。
- 提交信息。主题用命令式、约 50 字符、不加句号;正文说明“为什么”(问题、约束、被否决的替代方案),约 72 字符换行,与主题间空一行。
- 推送。在特性分支上使用 git push -u origin <branch>;必须改写已推送历史时用 git push --force-with-lease,绝不用裸 --force。
- 开 PR。描述必须包含改动内容与原因(关联 issue/需求)以及如何验证(具体命令或步骤、前后对比),并粘贴已运行的验证输出。
- 闭环评审意见。用 gh pr view <n> --comments 等拉取未解决评论,逐条处理或回复说明为何不处理,然后解决该线程,推送后续提交并留言指向它。
- 修复失败 CI 需读日志。用 gh run view <run-id> --log-failed 找到失败步骤和错误,本地复现并运行相同命令,修复后本地确认通过再推送;无代码改动就重跑 CI 属盲目重试,仅已知基础设施故障时才可如此并说明。
- 并行工作用独立 worktree。用 git worktree add ../repo-feature-x feature-x 给每个分支独立目录,完成后用 git worktree remove ../repo-feature-x 移除;更多内容见 references/worktrees.md。
限制与注意事项:裸 --force 可能静默丢弃他人提交;add -A 可能把 .env、凭据或无关编辑带入历史;盲目重跑 CI 可能掩盖间歇性缺陷;遗漏清理的 worktree 会保留陈旧分支与构建产物;PR 描述若只复述 diff 则无效;修复后不回复或解决线程会让评审者重复检查。不应做的事:不读暂存 diff 就用 add -A/add .、对共享分支裸 force、直接推默认分支、用户未要求时提交、用“Added X”式主题、PR 无验证步骤、无代码改动重跑 CI。
适用场景:需要按仓库规范完成提交、推送、开 PR、响应评审和修复 CI 的开发工作流,以及多个分支并行开发时的隔离。