Skip to content

Commit 758bda6

Browse files
committed
docs(sync-worktree): 为技能文档添加合并回主分支模式
添加 `--merge` 参数的使用说明,详细描述将 feature 分支合并到主分支的完整流程,包括状态检查、同步建议、合并预览和冲突处理步骤。
1 parent 042d032 commit 758bda6

1 file changed

Lines changed: 95 additions & 1 deletion

File tree

.claude/skills/sync-worktree/SKILL.md

Lines changed: 95 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,8 @@ git worktree list --porcelain
4646

4747
1. **无参数** → 状态概览模式(跳转 Step 3)
4848
2. **`--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

Comments
 (0)