Git Worktree 實戰 Playbook

建立：2026-04-24（Session 21）｜狀態：有效 與 dev/CLAUDE.md「Git Worktrees 使用 SOP」配套。SOP 給規範，Playbook 給實戰細節。 首次建立於 2026-04-24 真實並行試跑（tzlth-hq repo，兩個任務並行：主目錄建本 playbook + worktree 強化 SOP Troubleshooting 章節）。

---

一、何時該用（決策樹）

Q1：是同一 repo 嗎?
  ├─ 否（不同系統 / 不同 repo）→ 不用 worktree（天然隔離）
  └─ 是
      ↓
Q2：真的需要並行嗎?（另一件事不能等）
  ├─ 否（順序做即可）→ 用 git stash 就好
  └─ 是
      ↓
Q3：並行時間預期 > 30 分鐘?
  ├─ 否（< 30 分鐘）→ stash/pop 仍較快
  └─ 是 → ✅ 用 worktree

決策判準精煉：同 repo + 真並行 + 長時間 → 三者皆 Yes 才用。

---

二、5 個核心指令速查

---

三、本次實戰記錄（2026-04-24 Session 21）

以下為首次完整走 Git Worktree SOP 7 Step 的真實操作與時間紀錄。 目的：同時完成「建立本 playbook」與「補強 dev/CLAUDE.md Troubleshooting 章節」兩個獨立任務。

情境設計

• 任務 A（主目錄 main 分支）：建立 knowledge/operations/worktree-playbook.md
• 任務 B（worktree feat/worktree-sop-enhancement 分支）：補強 dev/CLAUDE.md Git Worktrees SOP 加入 Windows + Troubleshooting 章節

Step-by-Step 實際紀錄

Step 1：主目錄開始任務 A（建立 playbook 初稿）

cd C:/Users/USER/Desktop/tzlth-hq
# 建立本檔 knowledge/operations/worktree-playbook.md（初稿）
git add knowledge/operations/worktree-playbook.md
git commit -m "docs: worktree-playbook 初稿（Step 1-2 完成）"

時間：< 1 分鐘
commit：待本次執行後補

Step 2：建立 worktree

🔴 首次失敗(實戰真實錯誤)：

git worktree add ../tzlth-hq-worktree-demo feat/worktree-sop-enhancement
# fatal: invalid reference: feat/worktree-sop-enhancement

原因：git worktree add <path> <branch> 的 <branch> 預設是 checkout 既有分支；若分支不存在會直接報錯。建新分支必須加 -b flag。

正確指令：

git worktree add -b feat/worktree-sop-enhancement ../tzlth-hq-worktree-demo
# Preparing worktree (new branch 'feat/worktree-sop-enhancement')
# HEAD is now at f2a61ca docs: worktree-playbook 初稿（Step 1/7）

時間：首次失敗 + 重試 < 30 秒

📝 教訓：dev/CLAUDE.md 原 SOP 範例 git worktree add ../booking-gcal-fix hotfix/gcal-history 隱含假設 hotfix 已存在；實戰中「建新分支」才是常態 → 已在本次 Step 3 更新 SOP 加入 -b flag 的 troubleshooting 條目。

Step 3：在 worktree 中執行任務 B

cd ../tzlth-hq-worktree-demo
# 修改 dev/CLAUDE.md 在 Git Worktrees 使用 SOP 章節末尾補「Windows 與 Troubleshooting 補遺」
git add dev/CLAUDE.md
git commit -m "docs(dev): Git Worktrees SOP 補 Windows + troubleshooting"

時間：約 3 分鐘（含內容撰寫）

Step 4：回主目錄繼續任務 A（完善 playbook）

cd ../tzlth-hq   # 或打開第二個 Git Bash 視窗
# 補「實戰驗證」章節、「常見問題」章節
git add knowledge/operations/worktree-playbook.md
git commit -m "docs: worktree-playbook 補實戰驗證 + 常見問題"

時間：約 10 分鐘（含內容撰寫）

Step 5：主目錄 merge worktree 分支

git merge feat/worktree-sop-enhancement

預期：不會 fast-forward（因為 main 有 Step 1 + Step 4 兩個 commit，feat 有 Step 3 一個 commit），產生 merge commit；因為兩邊改的是不同檔案（playbook.md vs dev/CLAUDE.md），無 conflict 時間：< 10 秒

Step 6：清理

git worktree remove ../tzlth-hq-worktree-demo
git branch -d feat/worktree-sop-enhancement
git worktree list   # 驗證只剩主目錄

時間：< 10 秒

Step 7：push 到遠端

git push

實際 push 內容：main 的 3 個 commit（Step 1 + Step 4 + merge commit），worktree 分支不 push（已刪）

---

四、與主目錄的差異

---

五、反模式（不該用 worktree 的情境）

見 dev/CLAUDE.md 既有「不適用情境」章節，本 Playbook 補充：

• 需要在主目錄跑 hook 批量操作時（例：hook 檢查 staged files，worktree 的 stage 狀態與主目錄獨立）
• Windows IDE（VSCode）同時打開兩個 worktree 時，node_modules 可能被 symlink 搞混 → 不同 worktree 各自 npm install 較安全
• 短時間（< 30 分鐘）切換：stash/pop 仍較快，worktree 建立/清理成本偏高

---

六、與既有收尾七件事的關係

⛔ 收尾七件事一律在主目錄執行：

• tasks.md 完成標記、inventory.json 更新、daily-log.md、reflection-log.md、對話品質自查、未完成任務快照 → 全部在主目錄
• worktree 只做「程式碼/文件修改 + feature branch commit」
• 理由：收尾七件事牽涉跨檔案記錄（tasks + inventory + reports），在 worktree 跑容易狀態混亂

---

七、常見問題與排查

---

八、參考

• dev/CLAUDE.md → 「Git Worktrees 使用 SOP」（規範源頭）
• 本次實戰 commit 連結：見 tzlth-hq repo Session 21 commits（2026-04-24）
• 官方文件：https://git-scm.com/docs/git-worktree