Using Git Worktrees Skill

Using Git Worktrees 是 Superpowers 中的開發環境型 skill，專注於使用 Git worktrees 功能進行隔離的並行開發，讓你能夠同時在多個分支上工作而不需要頻繁切換。

何時使用

在以下情況中使用 Using Git Worktrees skill：

✅ 必須使用的情境：

• 需要同時在多個分支上工作
• 需要在 hotfix 期間繼續功能開發
• 需要並行處理多個獨立任務
• 需要同時執行不同分支的測試或建置
• 頻繁的分支切換影響開發效率

❌ 不適合的情境：

• 只在單一分支上工作
• 任務之間有強烈的相依性
• 磁碟空間非常有限
• 不熟悉 Git 基礎操作

Git Worktrees 的優勢

1. 真正的並行開發

傳統方式：
分支 A → 工作目錄（切換分支會影響當前狀態）
分支 B → 需要切換，可能會有未提交的變更衝突

Worktrees 方式：
分支 A → worktree-a/（獨立工作目錄）
分支 B → worktree-b/（獨立工作目錄）
分支 C → worktree-c/（獨立工作目錄）

所有 worktrees 可以同時存在和工作！

2. 避免狀態汙染

問題場景：
1. 在 feature 分支開發中（有未提交的變更）
2. 緊急 hotfix 需要處理
3. 必須 stash 或 commit 當前變更才能切換
4. 容易忘記恢復 stash

使用 worktrees：
1. 在 feature 分支開發中（有未提交的變更）
2. 建立新的 worktree 用於 hotfix
3. 在 hotfix worktree 中工作
4. feature worktree 的變更不受影響

3. 同時測試多個分支

使用情境：
- 同時執行不同分支的測試
- 同時啟動不同版本的前後端
- 同時檢視不同版本的 UI
- 比較不同分支的效能差異

Worktree 基礎操作

建立新的 Worktree

# 語法
git worktree add <路徑> <分支>

# 範例 1：基於現有分支建立 worktree
git worktree add ../feature-login feature/login

# 範例 2：建立新分支的 worktree
git worktree add ../hotfix-fix -b hotfix/fix-critical-bug

# 範例 3：基於特定 commit 建立 worktree
git worktree add ../experiment-a1a2b3c a1a2b3c

列出所有 Worktrees

git worktree list

# 輸出示例：
# /path/to/main/repo                1a2b3c4d [main]
# /path/to/feature-login            5e6f7g8h [feature/login]
# /path/to/hotfix-fix               9i0j1k2l [hotfix/fix-critical-bug]

移除 Worktree

# 語法
git worktree remove <路徑>

# 範例
git worktree remove ../feature-login

# 或先刪除目錄再清理
rm -rf ../feature-login
git worktree prune

實際使用場景

場景 1：Hotfix 期間繼續功能開發

情境：正在開發功能時收到緊急 hotfix 需求

# 第 1 步：當前在 feature 分支開發中
$ git branch
* feature/new-ui

# 有未提交的變更...
$ git status
modified:   src/components/NewUI.tsx

# 第 2 步：建立 hotfix worktree（不影響當前變更）
$ git worktree add ../hotfix-session -b hotfix/critical-bug

# 第 3 步：切換到 hotfix worktree
$ cd ../hotfix-session

# 第 4 步：修復 bug
$ vim src/utils/bugFix.js
$ git add src/utils/bugFix.js
$ git commit -m "fix: critical bug in session handling"

# 第 5 步：合併 hotfix 到 main
$ git checkout main
$ git merge hotfix/critical-bug
$ git push origin main

# 第 6 步：回到 feature worktree 繼續開發
$ cd ../../main/repo  # 回到原始 worktree
# feature/new-ui 的變更仍然存在！
$ git status
modified:   src/components/NewUI.tsx

場景 2：並行處理多個功能

情境：需要同時開發多個獨立功能

# 建立三個並行的 worktrees
$ git worktree add ../feature-auth -b feature/auth
$ git worktree add ../feature-payment -b feature/payment
$ git worktree add ../feature-notification -b feature/notification

# 現在可以在三個目錄中同時工作
$ cd ../feature-auth
# 開發認證功能...

# （在另一個終端）
$ cd ../feature-payment
# 開發支付功能...

# （在第三個終端）
$ cd ../feature-notification
# 開發通知功能...

# 每個功能都有獨立的測試和建置

場景 3：同時測試前端和後端

情境：全端開發，需要同時執行不同分支的前後端

# 前端分支
$ git worktree add ../frontend-feature-a -b feature/frontend-a

# 後端分支
$ git worktree add ../backend-api-v2 -b feature/backend-v2

# 啟動兩個終端同時運行

# 終端 1：前端
$ cd ../frontend-feature-a
$ npm run dev
# 前端運行在 http://localhost:3000

# 終端 2：後端
$ cd ../backend-api-v2
$ npm run dev
# 後端運行在 http://localhost:4000

# 可以同時測試前後端的整合！

場景 4：Code Review 時的並行測試

情境：審查 PR 時需要在本地測試，但不想影響當前工作

# 當前在 feature 分支工作
$ git branch
* feature/my-work

# 需要 review 其他人的 PR
$ git fetch origin
$ git worktree add ../review-pr-123 origin/pr/123

# 在新的 worktree 中測試 PR
$ cd ../review-pr-123
$ npm install
$ npm test
$ npm run dev

# 測試完成後移除 worktree
$ cd ..
$ rm -rf review-pr-123
$ git worktree prune

# 回到自己的工作
$ cd -
# feature/my-work 的變更仍然完好！

Worktree 管理最佳實踐

1. 清晰的命名慣例

# 好的命名
../worktree-feature-login
../worktree-hotfix-session-bug
../worktree-experiment-react-18

# 避免模糊的命名
../temp1
../test
../a

2. 定期清理

# 查看所有 worktrees
git worktree list

# 移除不再需要的 worktree
git worktree remove <路徑>

# 清理已刪除的 worktree 引用
git worktree prune

3. 追蹤 Worktree 用途

# 在每個 worktree 的 README 中說明用途
# worktree-hotfix/README.md
這個 worktree 用於修復生產環境的 critical bug。

分支：hotfix/fix-session-expiry
建立日期：2026-07-15
負責人：Alice
預計完成：2026-07-16

4. 避免重複建置

# 使用符號連結共享 node_modules
# 在主目錄
$ cd ../worktree-feature-auth
$ ln -s /path/to/main/repo/node_modules node_modules

# 或使用 pnpm 的 workspace 功能

常見問題和解決方案

問題 1：Worktree 路衝突

情境：嘗試建立 worktree 但路徑已存在

$ git worktree add ../existing-path feature/branch
fatal: '../existing-path' already exists

解決方案：
1. 確認路徑是否真的是空目錄
2. 如果是舊的 worktree，先清理
   $ rm -rf ../existing-path
   $ git worktree prune
3. 使用不同的路徑

問題 2：Branch 已被其他 Worktree 使用

情境：嘗試檢出已經在另一個 worktree 中的分支

$ git checkout feature/branch
fatal: 'feature/branch' is already checked out at '../worktree-feature'

解決方案：
1. 確認哪個 worktree 在使用該分支
   $ git worktree list
2. 如果要繼續，移除該 worktree
   $ git worktree remove ../worktree-feature
3. 或使用新分支
   $ git checkout -b feature/branch-2

問題 3：Commit 同步問題

情境：在不同 worktree 中提交同一分支的 commit

# worktree-a 中的 commit 還沒出現在 worktree-b 中

解決方案：
1. 在 worktree-b 中執行
   $ git fetch

2. 或者重置分支
   $ git reset --hard origin/branch-name

注意：這會丟棄本地的未提交變更！

Worktree 與其他工具整合

與 IDE 整合

VSCode：

# 在不同的 VSCode 實例中開啟不同 worktree
$ code ../worktree-feature-a
$ code ../worktree-feature-b

JetBrains IDEs：

• 可以直接開啟不同 worktree 作為獨立專案
• 每個專案有獨立的索引和快取

與 CI/CD 整合

# 在 CI 中使用 worktree 並行測試
# .github/workflows/test.yml

jobs:
  test-parallel:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      # 建立多個 worktree 並行測試
      - name: Test feature branches
        run: |
          git worktree add ../test-feature-1 feature/test-1
          git worktree add ../test-feature-2 feature/test-2
          
          cd ../test-feature-1 && npm test
          cd ../test-feature-2 && npm test

進階技巧

1. Worktree 模板

# 建立一個 worktree template 目錄
# 包含預先配置好的設定檔

template-worktree/
├── .vscode/
│   └── settings.json    # 預配置的 IDE 設定
├── .env.local          # 本地環境變數
└── README.md           # worktree 用途說明

# 建立新 worktree 時複製模板
$ cp -r template-worktree/* ../new-worktree/
$ git worktree add ../new-worktree -b feature/new-work

2. 自動化 Worktree 管理

# 建立腳本自動化管理 worktrees
#!/bin/bash
# manage-worktrees.sh

list_worktrees() {
  git worktree list
}

create_worktree() {
  local branch=$1
  local name=$(basename $branch)
  git worktree add ../worktree-$name $branch
}

cleanup_old() {
  # 移除超過 30 天的 worktrees
  find .. -maxdepth 1 -type d -name "worktree-*" -mtime +30 -exec rm -rf {} \;
  git worktree prune
}

case "$1" in
  list) list_worktrees ;;
  create) create_worktree $2 ;;
  cleanup) cleanup_old ;;
  *) echo "Usage: $0 {list|create|cleanup}" ;;
esac

3. Worktree 狀態監控

# 定期檢查所有 worktrees 的狀態
for wt in $(git worktree list | awk '{print $1}'); do
  echo "=== $wt ==="
  cd $wt
  git status -s
  cd -
done

與其他 Skills 組合

推薦組合

Git Worktrees + Finishing Development Branch

using-git-worktrees → finishing-a-development-branch

使用 worktree 並行處理多個分支，然後分別完成

Git Worktrees + Parallel Agents

using-git-worktrees → dispatching-parallel-agents

在不同 worktree 中並行執行獨立的開發任務

最佳實踐總結

Do’s ✅

• ✓ 使用清晰的命名慣例
• ✓ 定期清理不再需要的 worktrees
• ✓ 在每個 worktree 中記錄用途
• ✓ 使用 git worktree prune 清理孤立引用
• ✓ 追蹤 worktree 的磁碟空間使用

Don’ts ❌

• ✗ 不要在多個 worktree 中同時修改同一分支
• ✗ 不要忘記清理舊的 worktrees
• ✗ 不要在 worktree 中進行複雜的 rebase 操作
• ✗ 不要忽略磁碟空間的使用
• ✗ 不要在生產環境中使用 worktrees

Using Git Worktrees 讓並行開發變得簡單且高效，是提升開發工作流程的強大工具！