Git Worktree Flow

Git worktree 工作流（中文为主）

本 Skill 的目标：先创建 Git worktree，把本次需求放到独立分支/独立目录里做；过程中在该分支里持续提交；完成后询问是否合并回主分支，并在确认后清理 worktree 与分支。

默认约定（可按需覆盖）

• 主分支/基线分支（base）：优先使用 origin/HEAD 指向的默认分支；否则尝试 main / master；再否则用当前分支。
• worktree 目录：默认放在仓库根目录的 .worktrees/<branch>（会写入本地 info/exclude，避免污染 git status）。
• 分支命名：默认 wt/<YYYYMMDD-HHMM>-<slug>（slug 从需求中提取/简化）。
• 合并策略：默认 --no-ff --no-edit 的 merge commit；如用户偏好，可改为 squash。

核心流程

0) 先冻结需求（避免创建 worktree 后跑题）

• 用 1–3 句复述用户需求与验收标准（中文为主）。
• 记录一个简短 slug（用于分支名），例如：fix-player-cache、feat-search-ui。

1) 创建 worktree（必须先做）

1. 确认当前目录在 Git 仓库内：git rev-parse --show-toplevel

2. 如当前工作区有未提交修改，优先先提交或 stash；不建议直接创建 worktree 然后把"脏状态"带过去。

3. 确认 base 分支（优先 origin/HEAD 指向的默认分支，否则用 main / master，再否则用当前分支）。

4. 用 git worktree add 创建 worktree：

   • 自动生成分支名 + worktree 路径（推荐）：

     branch="wt/$(date +%Y%m%d-%H%M)-<slug>"
     path=".worktrees/wt-$(date +%Y%m%d-%H%M)-<slug>"
     git worktree add -b "$branch" "$path" <base>
     

   • 显式指定 base / branch / path：

     git worktree add -b wt/20260203-fix-player .worktrees/wt-20260203-fix-player main
     

5. 将 worktree 目录加入 info/exclude（避免污染 git status）：

   echo ".worktrees/" >> $(git rev-parse --git-common-dir)/info/exclude
   

2) 在 worktree 中完成需求（并持续提交）

1. cd <worktree_path>
2. 在该 worktree 内完成用户需求（实现 / 修复 / 重构 / 文档 / 测试等）。
3. 持续提交（强制习惯）：
   • 每个可验证的小步提交一次；提交前先运行最相关的验证命令（例如 go test ./... / npm run lint / 目标用例）。
   • 典型节奏：改动 → 验证 → git add -A → git commit -m "fix: ..." → 下一步。
   • 若用户明确要求整理提交历史，再考虑最后 squash；否则优先保留"可回滚的小步提交"。

3) 完成后询问：是否合并回主分支 + 是否清理

在你认为需求已完成且验证通过后，必须问用户一个明确问题（默认推荐选项放在最前）：

• A（推荐）合并到 base，然后删除 worktree 与分支
• B 合并到 base，但保留 worktree（方便复查/后续改动）
• C 暂不合并，只给出 worktree 路径与分支名（交由用户决定）

若用户选择 A 或 B：

1. 在主工作区（不是 worktree）执行合并：
   • 切换回主工作区并切到 base 分支：

     cd <主仓库目录>
     git checkout <base>
     

   • 合并 worktree 分支：

     git merge --no-ff --no-edit <worktree分支名>
     

   • 切换回原分支（可选）：

     git checkout -
     

若用户选择 A（合并 + 清理）：

1. 删除 worktree（保留分支）：

   git worktree remove <worktree路径>
   

2. 删除已合并的分支：

   git branch -d <worktree分支名>
   

若用户选择 C：

• 只输出：worktree 路径、分支名、base 分支、建议的后续命令（merge/cleanup），不要做任何合并/删除。

安全护栏（必须遵守）

• 合并与删除属于高风险动作：必须在执行前再次确认用户选择，并说明会执行哪些命令。
• 不要 -D 强删分支；除非用户明确同意，并且你已解释风险。
• 如果合并/删除失败，停止自动化流程，输出"可复制粘贴"的手工恢复/处理步骤。

常见问题

• worktree 目录出现在 git status：将 .worktrees/ 加入 $(git rev-parse --git-common-dir)/info/exclude 以忽略。
• worktree add 提示分支已存在：用 --branch 指向已有分支，或先清理旧 worktree。
• 合并冲突：停止并提示用户；在主工作区解决冲突、提交，再继续 cleanup。