git-ship — 一键 Git 工作流

目标与成功标准

把当前工作区的改动，完整走完这条路径：

当前改动 → 基于最新 main 切新分支 → commit → PR → squash merge → 回 main

用户调用 ship 就表示已经授权执行整条工作流。流程应连续完成，不要为分支名、 commit message、PR 标题、PR 正文、冲突解决方案、验证修复或是否继续等信息请求确认。

这份授权包括：

• 修改当前功能代码，使它与最新 main 的线上功能兼容。
• 修改由本次改动或冲突引起的测试、lint、类型、构建和 CI 问题。
• 创建必要的修复提交并重复推送。
• 在合并前同步最新 main，解决新产生的冲突并重新验证。

只有同时满足以下条件才算完成：

1. PR 已成功合并到 main，不能把“PR 已创建”或“已开启自动合并”当作完成。
2. 必需检查已经通过，或仓库没有可运行的检查。
3. 本地回到 main 并尽可能快进到合并后的提交。

核心执行原则

• ship 的默认结果是“发布成功”，不是“发现问题后把问题交还给用户”。
• 命令失败后先判断原因并恢复流程；不要机械重复同一个失败命令。
• 以最新 origin/main 的现有线上能力和当前改动的产品目标为共同约束，优先保留两者。
• 修复根因，不通过跳过测试、删除断言、关闭规则或使用 --no-verify 制造假通过。
• 不使用 force push、reset --hard、丢弃提交或覆盖用户改动等破坏性手段。
• 只有缺少认证/权限、必须由他人审批、平台或网络持续不可用、需求意图确实无法从代码和上下文判断时，才暂停并说明唯一需要用户处理的事项。

第 0 步：信息收集

开始前先检查现状：

git status --short --branch
git branch --show-current
git diff --stat
git diff --cached --stat
git remote -v
gh auth status

同时记录当前分支、未提交改动和未推送提交，防止遗漏用户工作。没有未提交改动时， 继续检查当前分支相对 origin/main 是否存在待发布提交；两者都没有才提示没有可发布内容并停止。

自动确定以下信息：

1. 分支名

• 用户已经提供时直接使用。
• 否则根据改动内容推断，格式为 <type>/<short-desc>。
• 遵循目标仓库已有分支前缀或命名规则；没有规则时使用语义化名称。
• 本地或远端同名分支已存在时，自动增加简短后缀，避免因命名冲突中断。

2. Commit message

• 用户已经提供时直接使用。
• 否则根据完整 diff 生成 Conventional Commits 格式：<type>(<scope>): <description>。

3. PR 标题和正文

• PR 标题默认使用 commit message。
• PR 正文根据 diff 自动生成 2–3 条 Summary、改动文件概览和验证结果。
• 不单独询问 PR 名称或正文。

确定后简短告知用户即将使用的分支和 commit，然后立即继续，不等待回复。

第 1 步：同步主分支

有工作区改动时先创建带唯一标识的 stash，并记录对应引用；没有改动时不要创建空 stash。

git stash push --include-untracked -m "git-ship: <timestamp>"
git fetch --prune origin

fetch 后以第 0 步记录的原分支和原 HEAD 为基准检查待发布提交。原功能分支已有提交时保留该分支，直接合并 origin/main，随后恢复本次 stash；不能先切到 main 再决定原分支是否有提交。只有原分支没有待发布提交时才从 origin/main 新建发布分支。

先从远端 HEAD 或仓库配置核对目标主分支；下文 main 是占位名称，仓库使用 master 等名称时全部替换为实际分支。

告知用户最新主分支的 commit hash。

如果本地 main 无法 fast-forward：

1. 检查本地独有提交，不能删除或覆盖它们。
2. 直接从最新 origin/main 创建发布分支，继续发布流程。
3. 在最终回到 main 时保留这些本地提交，并明确说明本地 main 未被覆盖；这不影响已经完成的线上合并。

第 2 步：创建分支

git checkout -b <branch-name> origin/main

如果当前工作已经位于包含待发布提交的功能分支，可以继续使用它；先合并最新 origin/main 并按“冲突处理流程”解决问题。不要把相同改动重复提交。

第 3 步：恢复改动并提交

git stash apply <recorded-stash>
git add -A
git commit -m "<commit-message>"

stash apply 发生冲突时，按“冲突处理流程”自行解决。确认所有改动已经恢复并提交后， 再删除本次创建的 stash；不要误删用户已有 stash。

提交钩子失败属于验证失败：修复根因、重新暂存并再次提交，不要使用 --no-verify。

冲突处理流程

以下流程适用于 stash apply、合并最新 main、远端分支非 fast-forward 和 PR 合并冲突。

1. 获取事实：

   git status
   git diff --name-only --diff-filter=U
   git log --oneline --left-right origin/main...HEAD

2. 逐个查看冲突文件的 base、当前分支和对方版本，并阅读相关调用方、测试、类型、 配置和近期提交。不要只看冲突标记，也不要整文件盲选 ours 或 theirs。
3. 判断两边意图：
   • origin/main 代表当前线上行为，除非本次功能明确替换它，否则必须保留。
   • 当前分支代表本次功能目标，不能为了消除冲突而静默删除。
   • 两边都新增有效能力时，整合接口、数据流和边界条件，让它们同时成立。
   • 测试冲突按最终产品行为更新；锁文件和生成文件使用仓库规定的工具重新生成。
4. 编辑到没有冲突标记，执行 git add，确认 git diff --name-only --diff-filter=U 为空。
5. 运行与冲突文件相关的最小验证，再运行仓库要求的完整验证。
6. 创建合并或修复提交，继续原流程。

如果无法仅凭冲突块判断，应继续从实现、测试、调用链、提交历史和项目文档收集证据。 只有两种行为互斥且产品意图仍无法判断时才询问用户，并把选项、影响和推荐结论一次说清。

第 3.5 步：本地验证

根据当前改动和仓库说明，寻找已有验证命令：

1. 优先读取 AGENTS.md、CONTRIBUTING.md 和 README.md。
2. 再检查 package.json、pyproject.toml、Makefile、CI 配置等项目文件。
3. 必要时按锁文件使用项目既有包管理器安装依赖，不擅自升级依赖。
4. 先运行与改动范围直接相关的检查，再运行仓库要求的 lint、typecheck、test 或 build。
5. 找不到可信命令时，明确告知用户跳过了哪些验证以及原因，不要自行编造命令。

验证失败修复循环

验证失败时不要暂停，按以下循环处理：

1. 保留完整错误输出，定位第一个根因，而不是只修最后一个连锁报错。
2. 判断失败来自产品代码、测试预期、类型、格式、依赖、配置还是环境。
3. 做满足线上功能与当前功能的最小正确修复：
   • 优先使用仓库已有的 formatter 或 lint autofix，再处理剩余问题。
   • 代码缺陷修代码。
   • 测试仅在本次功能有意改变行为、原预期已经过时时更新；不得弱化、跳过或删除有效测试。
   • 环境缺少依赖时按项目锁文件恢复环境；不得借机做无关升级。
4. 先重跑失败的最小检查，再重跑全部必需检查。
5. 发现新失败就继续诊断和修复，直到全部通过。

首次 push 前产生的修复可以纳入当前提交；首次 push 后产生的修复创建新提交并正常 push， 不要为了整理历史而 force push。只要每轮都有新证据或实质进展，就继续推进，不因失败次数多而放弃。

第 4 步：推送并创建 PR

git push -u origin <branch-name>

push 被拒绝时先分类处理：

• 远端同名分支是无关内容：自动换一个唯一分支名并推送。
• 远端同名分支属于同一功能且有新提交：fetch 后合并远端分支，解决冲突、验证并再次 push。
• 网络或 GitHub 临时失败：短暂重试并检查服务恢复情况。
• 认证或写权限缺失：保留完整工作现场并请求用户完成授权。

使用 gh pr create 创建 PR：

• base 为 main
• head 为新分支
• 标题使用 commit message
• 正文包含 2–3 条 Summary、改动文件概览、验证结果和 🤖 Shipped via git-ship

如果 PR 已存在则复用，不重复创建。创建成功后向用户展示 PR URL，然后继续，不等待回复。

第 5 步：等待 CI 并修复

使用 gh pr checks <pr-number> --watch 等仓库可用命令等待必需检查。

检查失败时：

1. 用 gh pr checks、gh run view --log-failed 等命令读取失败任务和日志。
2. 能本地复现时先复现，按“验证失败修复循环”修复根因。
3. 提交修复并正常 push，重新等待 CI。
4. 重复直到必需检查全部通过。

如果检查长期 pending，检查 workflow、并发队列和 GitHub 状态；能重新运行失败任务时自行处理。 只有任务必须由有权限的人批准或外部服务持续不可用时才请求用户介入。

第 6 步：同步最新 main 并 Squash 合并

合并前再次同步主分支：

git fetch origin main
git merge --no-edit origin/main

有冲突时按“冲突处理流程”解决，重新跑本地验证、push 并等待 CI。然后直接合并：

gh pr merge <pr-number> --squash --delete-branch

如果合并时提示 base 更新或冲突，重新执行同步、解决、验证、push、等待 CI 的闭环，再次合并。 如果仓库支持合并队列，进入队列后持续等待，直到确认 PR 已实际合并。

不得绕过分支保护。缺少必需审批、签名或权限时，这是外部阻塞：展示 GitHub 的准确返回信息， 说明已经完成的步骤和用户只需完成的动作。

第 7 步：回到 main 并确认结果

git checkout main
git pull --ff-only origin main
git status --short --branch
gh pr view <pr-number> --json state,mergedAt,mergeCommit,url

确认 PR 状态为 merged，并打印最终 main commit hash。如果本地 main 有预先存在的独有提交而 无法 fast-forward，保留它们，不做破坏性处理；仍应确认远端 PR 已合并并把本地状态讲清楚。

打印最终状态：

🚀 Ship 完成！
  ✓ 分支 <branch-name> 已合并到 main
  ✓ 本地验证和必需 CI 已通过
  ✓ 当前在 main，已同步最新代码（<commit-hash>）
  ✓ PR: <pr-url>

错误处理原则

• 每步操作前简短说明正在做什么。
• 任何命令失败后先诊断、修复并重试，继续以成功合并为目标。
• 不使用 force push、reset --hard 或其他破坏性恢复方式。
• 主动解决冲突，并同时保护最新线上功能和当前功能目标。
• 主动修复测试、lint、类型检查、构建、提交钩子和 CI 失败。
• 不为自动推断的分支名、commit message、PR 标题、PR 正文或继续执行请求确认。
• 不把可修复的失败、需要多轮调试或流程耗时当作阻塞。
• 只有当前环境确实无法解决的外部条件才暂停；保留可继续工作的分支、提交和日志。
• 暂停时只给出明确、最小、可执行的用户动作，完成后可从原位置继续。

常见边界情况