git:merge-worktree

Claude 命令：合并工作树

你的任务是帮助用户将 Git 工作树中的更改合并到当前分支，支持从简单的文件检出到选择性挑选提交等多种合并策略。

说明

重要：严格按照以下步骤执行：

1. 检查当前状态：运行 git worktree list 显示所有现有工作树，并运行 git status 确认工作目录状态

2. 解析用户输入：确定用户想要执行的合并操作：

   • --interactive 或不带参数：引导式交互模式
   • 文件／目录路径：从工作树合并指定文件或目录
   • 提交名称：挑选指定提交
   • 分支名称：从该分支的工作树进行合并
   • --from <worktree>：明确指定源工作树
   • --patch 或 -p：使用交互式补丁选择模式

3. 确定源工作树／分支： a. 如果用户指定了 --from <worktree>：直接使用该工作树路径 b. 如果用户指定了分支名称：从 git worktree list 中查找该分支对应的工作树 c. 如果只有一个其他工作树：询问用户是否确认将其用作源 d. 如果存在多个工作树：列出工作树，并询问用户要从哪个工作树合并 e. 如果不存在其他工作树：说明情况，并提供基于分支进行合并的选项

4. 确定合并策略：根据用户需求展示选项：

   策略 A：选择性检出文件（用于指定文件／目录）

   • 最适合：从其他分支获取完整文件
   • 命令：git checkout <branch> -- <path>

   策略 B：交互式补丁选择（用于部分文件更改）

   • 最适合：从文件中选择指定代码块／行
   • 命令：git checkout -p <branch> -- <path>
   • 对每个代码块询问用户：y（应用）、n（跳过）、s（拆分）、e（编辑）

   策略 C：选择性暂存的 Cherry-pick（用于指定提交）

   • 最适合：应用某个提交，但排除部分更改
   • 步骤：
     1. git cherry-pick --no-commit <commit>
     2. 检查已暂存的更改
     3. 使用 git reset HEAD -- <unwanted-files> 取消暂存
     4. 使用 git checkout -- <unwanted-files> 丢弃更改
     5. git commit -m "message"

   策略 D：手动合并并处理冲突（用于复杂合并）

   • 最适合：在控制冲突解决过程的同时合并整个分支
   • 步骤：
     1. git merge --no-commit <branch>
     2. 检查所有更改
     3. 选择性地暂存／取消暂存文件
     4. 如有冲突则解决冲突
     5. git commit -m "message"

   策略 E：多工作树选择性合并（从多个来源合并内容）

   • 最适合：从不同工作树中获取不同文件
   • 步骤：
     1. git checkout <branch1> -- <path1>
     2. git checkout <branch2> -- <path2>
     3. git commit -m "Merge selected files from multiple branches"

5. 执行所选策略：

   • 如果用户想要检查更改，先运行合并前对比（建议先使用 /git:compare-worktrees）
   • 执行所选策略对应的 Git 命令
   • 处理发生的任何冲突
   • 在最终提交前确认更改

6. 合并后摘要：显示已合并的内容：

   • 更改／新增／删除的文件
   • 源工作树／分支
   • 使用的合并策略

7. 清理提示：成功合并后，询问：

   • “你想移除任何工作树以清理本地状态吗？”
   • 如果是：列出工作树，并询问要移除哪些
   • 对选定的工作树执行 git worktree remove <path>
   • 如有需要，提醒用户运行 git worktree prune

合并策略参考

策略	适用场景	命令模式
选择性文件	需要其他分支中的完整文件	git checkout <branch> -- <path>
交互式补丁	需要文件中的特定更改	git checkout -p <branch> -- <path>
选择性摘取提交	需要某个提交，但不需要其中的所有更改	git cherry-pick --no-commit + 选择性暂存
手动合并	需要完整合并分支并进行控制	git merge --no-commit + 选择性暂存
多源合并	需要合并来自多个分支的文件	多次执行 git checkout <branch> -- <path>

示例

从工作树合并单个文件：

> /git:merge-worktree src/app.js --from ../project-feature
# Prompts for merge strategy
# Executes: git checkout feature-branch -- src/app.js

交互式选择补丁：

> /git:merge-worktree src/utils.js --patch
# Lists available worktrees to select from
# Runs: git checkout -p feature-branch -- src/utils.js
# User selects hunks interactively (y/n/s/e)

摘取特定提交：

> /git:merge-worktree abc1234
# Detects commit hash
# Asks: Apply entire commit or selective?
# If selective: git cherry-pick --no-commit abc1234
# Then guides through unstaging unwanted changes

从多个工作树合并：

> /git:merge-worktree --interactive
# "Select files to merge from different worktrees:"
# "From feature-1: src/moduleA.js"
# "From feature-2: src/moduleB.js, src/moduleC.js"
# Executes selective checkouts from each

完整引导模式：

> /git:merge-worktree
# Lists all worktrees
# Asks what to merge (files, commits, or branches)
# Guides through appropriate strategy
# Offers cleanup at end

存在冲突时合并目录：

> /git:merge-worktree src/components/ --from ../project-refactor
# Strategy D: Manual merge with conflicts
# git merge --no-commit refactor-branch
# Helps resolve any conflicts
# Reviews and commits selected changes

交互式补丁模式指南

使用 --patch 或策略 B 时，用户会看到针对每个更改块的提示：

@@ -10,6 +10,8 @@ function processData(input) {
   const result = transform(input);
+  // Added validation
+  if (!isValid(result)) throw new Error('Invalid');
   return result;
 }
Apply this hunk? [y,n,q,a,d,s,e,?]

按键	操作
y	应用此更改块
n	跳过此更改块
q	退出（不应用此更改块及其余更改块）
a	应用此更改块及所有剩余更改块
d	不应用此文件中的此更改块及其余更改块
s	拆分为更小的更改块
e	手动编辑此更改块
?	显示帮助

选择性摘取提交工作流

对于策略 C（选择性暂存的摘取提交）：

# 1. Apply commit without committing
git cherry-pick --no-commit abc1234

# 2. Check what was staged
git status

# 3. Unstage files you don't want
git reset HEAD -- path/to/unwanted.js

# 4. Discard changes to those files
git checkout -- path/to/unwanted.js

# 5. Commit the remaining changes
git commit -m "Cherry-pick selected changes from abc1234"

多工作树合并工作流

对于策略 E（从多个工作树合并）：

# Get files from different branches
git checkout feature-auth -- src/auth/login.js src/auth/session.js
git checkout feature-api -- src/api/endpoints.js
git checkout feature-ui -- src/components/Header.js

# Review all changes
git status
git diff --cached

# Commit combined changes
git commit -m "feat: combine auth, API, and UI improvements from feature branches"

常见工作流

获取功能文件但不完整合并

> /git:merge-worktree src/new-feature.js --from ../project-feature
# Gets just the file, not the entire branch

从热修复分支获取部分 Bug 修复

> /git:merge-worktree --patch src/utils.js --from ../project-hotfix
# Select only the specific bug fix hunks, not all changes

合并多个 PR 的更改

> /git:merge-worktree --interactive
# Select specific files from PR-1 worktree
# Select other files from PR-2 worktree
# Combine into single coherent commit

合并前审查

# First review what will be merged
> /git:compare-worktrees src/module.js
# Then merge with confidence
> /git:merge-worktree src/module.js --from ../project-feature

重要说明

• 工作目录状态：合并前务必确保工作目录干净。未提交的更改可能导致冲突。

• 合并前审查：合并前可考虑使用 /git:compare-worktrees，了解将应用哪些更改。

• 冲突解决：如果合并期间发生冲突，该命令会帮助你在提交前识别并解决冲突。

• 不提交标记：大多数策略使用 --no-commit，让你能够控制最终的提交消息以及要纳入的内容。

• 共享仓库：所有工作树共享同一个 Git 对象数据库，因此在任何工作树中创建的提交都能立即从其他工作树中摘取。

• 分支锁定：请记住，一个分支一次只能在一个工作树中检出。合并操作时请使用分支名称，而不要创建重复的工作树。

合并后的清理

合并后，可考虑清理不再需要的工作树：

# List worktrees
git worktree list

# Remove specific worktree (clean state required)
git worktree remove ../project-feature

# Force remove (discards uncommitted changes)
git worktree remove --force ../project-feature

# Clean up stale worktree references
git worktree prune

每次成功合并后，该命令都会提示你进行清理，以帮助保持工作区整洁。

故障排除

“无法合并：工作目录中有未提交的更改”

• 请先提交或暂存当前更改
• 或在合并前使用 git stash，合并后使用 git stash pop

“<file> 中存在合并冲突”

• 该命令会显示冲突文件
• 打开文件并解决冲突（查找 <<<<<<< 标记）
• 使用 git add <file> 暂存已解决的文件
• 使用 git commit 继续

摘取提交时“找不到提交”

• 确保提交哈希正确
• 在任意工作树中运行 git log <branch> 查找提交
• 所有工作树共享提交

“无法检出：工作树中已存在该文件”

• 文件有本地修改
• 请先提交、暂存或丢弃本地更改
• 然后重试合并操作

“找不到工作树对应的分支”

• 指定的工作树可能已被移除
• 运行 git worktree list 查看当前工作树
• 使用 git worktree prune 清理失效引用

与其他命令集成

合并前审查：

> /git:compare-worktrees src/
> /git:merge-worktree src/specific-file.js

创建工作树、合并并清理：

> /git:create-worktree feature-branch
> /git:compare-worktrees src/
> /git:merge-worktree src/module.js --from ../project-feature-branch
# After merge, cleanup is offered automatically