@@ -46,7 +46,8 @@ git worktree list --porcelain
4646
47471 . ** 无参数** → 状态概览模式(跳转 Step 3)
48482 . ** ` --all ` ** → 批量同步模式(跳转 Step 6)
49- 3 . ** ` <branch> ` ** → 单分支同步模式
49+ 3 . ** ` <branch> --merge ` ** → 合并回主分支模式(跳转 Step 7)
50+ 4 . ** ` <branch> ` ** → 单分支同步模式
5051 - 检查是否同时提供了 ` --from <base> ` ;如果有,使用该分支替代默认基准
5152 - 跳转 Step 4
5253
@@ -255,6 +256,99 @@ git -C <worktree-path> rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2
255256
256257---
257258
259+ ## Step 7: 合并回主分支(` --merge ` )
260+
261+ 当用户使用 ` /sync-worktree <branch> --merge ` 时,将指定 feature 分支合并到主分支(master)。
262+
263+ ### 7.1 验证目标分支
264+
265+ 同 Step 4.1,检查指定的分支名是否存在于 worktree 列表中。
266+
267+ ### 7.2 检查双方工作区状态
268+
269+ 分别检查 ** feature worktree** 和 ** 主 worktree** 的工作区状态:
270+
271+ ``` bash
272+ git -C < feature-worktree-path> status --porcelain
273+ git -C < main-worktree-path> status --porcelain
274+ ```
275+
276+ 任一方有未提交改动,** 拒绝** 合并:
277+ > ❌ ` <branch> ` 工作区有未提交改动,请先 commit 或 stash 后重试。
278+
279+ 或:
280+ > ❌ 主分支 ` <base> ` 工作区有未提交改动,请先 commit 或 stash 后重试。
281+
282+ ### 7.3 检查是否需要先同步
283+
284+ 检查 feature 分支是否落后于主分支:
285+ ``` bash
286+ git rev-list --count < branch> ..< base>
287+ ```
288+
289+ 如果计数 ** > 0** ,说明 feature 分支还没有包含主分支的最新 commit。** 建议用户先同步** :
290+ > ⚠ ` <branch> ` 落后 ` <base> ` N 个 commit,建议先执行 ` /sync-worktree <branch> ` 同步后再合并,以获得干净的 fast-forward merge。
291+
292+ 使用 ** AskUserQuestion** 让用户选择:
293+
294+ | 选项 | 说明 |
295+ | ------| ------|
296+ | 先同步再合并(推荐) | 先执行 rebase 同步,再 merge(产生 fast-forward) |
297+ | 直接合并 | 跳过同步,直接 merge(可能产生 merge commit) |
298+ | 取消 | 不执行任何操作 |
299+
300+ 如果用户选择「先同步再合并」,先执行 Step 4 的完整流程,成功后继续 Step 7.4。
301+
302+ ### 7.4 合并预览
303+
304+ 展示将要合并到主分支的 commit:
305+ ``` bash
306+ git log --oneline < base> ..< branch>
307+ ```
308+
309+ 显示格式:
310+ ```
311+ 将 merge <branch> into <base>
312+
313+ 包含 <N> 个 commit:
314+ <sha1> <message1>
315+ <sha2> <message2>
316+ ...
317+ ```
318+
319+ ### 7.5 执行 Merge
320+
321+ 在** 主 worktree** 目录中执行 merge:
322+ ``` bash
323+ git -C < main-worktree-path> merge < branch>
324+ ```
325+
326+ 如果 feature 分支已经 rebase 过,这通常是一个 ** fast-forward merge** (不产生额外的 merge commit)。
327+
328+ ** 如果 merge 成功** → 跳转 Step 7.6(成功报告)
329+
330+ ** 如果 merge 失败(冲突)** → 类似 Step 4.6 的冲突处理流程,但操作目录改为主 worktree:
331+ 1 . 列出冲突文件:` git -C <main-worktree-path> diff --name-only --diff-filter=U `
332+ 2 . 提供三个选项:Claude 协助解决 / 手动解决后 ` git -C <path> merge --continue ` / 中止 ` git -C <path> merge --abort `
333+
334+ ### 7.6 成功报告(Merge)
335+
336+ ``` bash
337+ git -C < main-worktree-path> rev-parse --short HEAD
338+ git -C < main-worktree-path> log --oneline -1
339+ ```
340+
341+ 报告格式:
342+ ```
343+ ✔ <branch> 已合并到 <base>
344+
345+ 新 HEAD: <short-sha> <message>
346+ 合并方式: fast-forward | merge commit
347+ 合并 commit: <N> 个
348+ ```
349+
350+ ---
351+
258352## 安全护栏
259353
260354- ** 禁止自动 stash** :工作区有未提交改动时,直接拒绝并告知用户先 commit 或 stash。
0 commit comments