Skip to main content

第 15 課：Git 工作樹

學習目標​

完成本課程後，您將能夠：

  • 瞭解什麼是 git worktree 以及為什麼它們有用
  • 使用 Claude Code 建立和管理 worktree
  • 使用 worktree 進行並行開發
  • 將 worktree 應用於常見的 Claude Code 工作流程
  • 高效地清理 worktree

先決條件​

  • 完成第 9 課 - Git 整合基礎
  • Git 2.7+ - 需要 Worktree 支援
  • 活躍開發 - 在具有多個分支的專案上工作

預估時間： 20 分鐘

什麼是 Git Worktree？​

問題​

傳統上，要同時在多個分支上工作：

# ❌ 傳統方法 - 緩慢且容易出錯
cd /project
git checkout feature-A
# 進行變更...
git commit -m "在功能 A 上工作"

git checkout feature-B  # 切換整個工作區
# 暫存或提交 feature-A 變更
# 在 feature-B 上進行變更...

問題：

  • 必須在切換前提交或暫存
  • 無法並行處理功能
  • 緩慢的情境切換
  • 意外混合變更的風險

解決方案：Git Worktree​

Git worktree 讓您擁有多個工作目錄用於同一個儲存庫，全部連結到同一個 git 儲存庫。

# ✅ Worktree 方法 - 快速且安全
project/                 # 主分支（main）
├── .git/               # 單一 git 儲存庫
project-feature-a/       # feature-a 的 worktree
project-feature-b/       # feature-b 的 worktree
project-hotfix/          # hotfix 的 worktree

好處：

  • 同時在多個分支上工作
  • 無需過早暫存或提交
  • 更快的情境切換
  • 隔離的開發環境
  • 非常適合 Claude Code 多代理工作流程！

使用 Claude Code 建立 Worktree​

基本 Worktree 建立​

方法 1：直接使用 git

git worktree add ../project-feature-a feature-a

方法 2：使用 Claude Code

您> 為 feature-a 分支建立一個 worktree

Claude：[使用 Bash 工具]
[執行] git worktree add ../project-feature-a feature-a
✓ Worktree 已建立於 ../project-feature-a

您> 現在開啟那個 worktree 並顯示我結構

Claude：[讀取目錄]
Worktree 已準備：
- 目前分支：feature-a
- 檔案：[與 main 相同]
- 未變更：所有檔案符合 main 分支

從提交建立 Worktree​

您> 從 commit abc1234 建立一個 worktree 來調查 bug

Claude：[建立 worktree]
git worktree add ../bug-investigation abc1234

✓ Worktree 已建立於 ../bug-investigation
  已檢出提交：abc1234
  Detached HEAD 狀態

列出 Worktree​

您> 顯示我此專案的所有 worktree

Claude：[使用 Bash 工具]
git worktree list

輸出：
/home/user/project              abc1234 [main]
/home/user/project-feature-a   def5678 [feature-a]
/home/user/project-hotfix      ghi9012 [hotfix-123]

Claude Code + Worktree：完美組合​

工作流程 1：並行功能開發​

情境： 您需要在處理功能 B 的同時審查功能 A。

設定：

# 終端機 1：功能 A 開發
cd ~/project-feature-a
claude
您> 實作使用者認證功能

# 終端機 2：功能 B 審查
cd ~/project-feature-b
claude
您> 審查付款整合變更

兩個 Claude Code 實例在自己的 worktree 中獨立工作！

工作流程 2：開發期間的 Hotfix​

情境： 在處理功能時發現關鍵 bug。

# 主開發
~/project/ (在 feature-x 上)

# 建立 hotfix worktree
您> 從 main 建立 hotfix 分支的 worktree

Claude：[建立 worktree]
cd ../project-hotfix
git checkout -b hotfix-critical-bug origin/main

# 切換到 hotfix
您> 切換到 hotfix worktree 並修正 bug

Claude：[調查並修正 bug]
已修正！問題在 auth.py 第 45 行。
已將修正提交到 hotfix 分支。

# 回到功能工作
[繼續在主 worktree 上處理 feature-x]

無需情境切換！

工作流程 3：多代理 Worktree​

結合 worktree 與多代理自動化：

project/
├── .agents/
├── worktrees/
│   ├── backend-api/          # Claude Code：後端代理
│   ├── frontend-ui/          # Claude Code：前端代理
│   └── integration-tests/    # Claude Code：測試代理
└── scripts/

編排腳本：

# 為代理設定 worktree
git worktree add ../backend-api feature/backend
git worktree add ../frontend-ui feature/frontend
git worktree add ../integration-tests feature/tests

# 在它們的 worktree 中啟動代理
./scripts/start-multi-agent-worktrees.sh

每個代理隔離工作！

常見 Worktree 模式​

模式 1：功能分支 Worktree​

# 開始新功能之前
您> 為新的 shopping-cart 功能建立 worktree

Claude：[執行]
git worktree add ../project-shopping-cart origin/main
cd ../project-shopping-cart
git checkout -b feature/shopping-cart

✓ 準備開發購物車功能

完成時：

# 合併和清理之後
您> 在合併後移除 shopping-cart worktree

Claude：[移除 worktree]
git worktree remove ../project-shopping-cart
✓ Worktree 已移除

模式 2：PR 審查 Worktree​

# 建立 worktree 以審查 PR
您> 為 PR #123 建立 worktree

Claude：[從 PR 建立 worktree]
git worktree add ../pr-123-review origin/pr/123
cd ../pr-123-review

# Claude Code 在隔離中審查 PR
您> 審查此 PR 並建議改進

模式 3：實驗 Worktree​

# 安全地嘗試實驗性變更
您> 建立實驗 worktree 以測試重構

Claude：[建立 worktree]
git worktree add ../experiment-refactor HEAD

# 進行風險變更而不影響主 worktree

管理 Worktree​

列出 Worktree​

您> 顯示所有 worktree 及其狀態

Claude：[列出 worktree]
git worktree list --porcelain

worktree /home/user/project
HEAD abc1234
branch refs/heads/main
detached

worktree /home/user/project-feature-a
HEAD def5678
branch refs/heads/feature-a

worktree /home/user/project-bug-fix
HEAD ghi9012
branch refs/heads/bug-fix

修剪 Worktree​

移除已刪除的 worktree：

您> 清理目錄已消失的 worktree

Claude：[修剪 worktree]
git worktree prune
✓ 已移除 3 個過時的 worktree 參考

移動 Worktree​

重新配置 worktree：

您> 將 hotfix worktree 移到 ~/projects/hotfix

Claude：[移動 worktree]
git worktree move ../project-hotfix ~/projects/hotfix
✓ Worktree 已移動

Worktree 最佳實踐​

1. 組織 Worktree​

好：

~/projects/
├── main-project/          # 主開發
├── project-feature-a/     # 功能 A
├── project-hotfix-123/    # Hotfix #123
└── project-experiment/    # 實驗

避免：

~/random-locations/scattered-around/

2. 清楚命名 Worktree​

好：

  • project-feature-shopping-cart
  • project-hotfix-auth-bug
  • project-refactor-database

壞：

  • project-1
  • temp
  • test

3. 定期清理​

您> 檢查哪些 worktree 可以移除

Claude：[分析 worktree]
這些 worktree 有已合併的分支：
- project-feature-completed（分支已合併到 main）
- project-hotfix-deployed（分支已刪除）

可以安全移除。

4. 與 Claude Code 工作階段一起使用​

最佳實踐： 每個 worktree 一個 Claude Code 工作階段

# 終端機 1
cd ~/project-feature-a
claude
# 處理功能 A

# 終端機 2
cd ~/project-feature-b
claude
# 處理功能 B

每個 Claude 實例只有其 worktree 的情境！

實用範例​

範例 1：功能開發期間的 Hotfix​

# 在主 worktree 中處理功能
~/project/ (在 feature/new-ui 上)

# 關鍵 bug 報告進來
您> 為緊急 bug 修正建立 worktree

Claude：[建立 worktree]
git worktree add ../project-hotfix-urgent origin/main
cd ../project-hotfix-urgent
git checkout -b hotfix/crash-bug

# 修正 bug
您> 調查崩潰 bug 並修正它

Claude：[分析並修正]
找到問題！auth.py:67 中的空指標。
已修正並提交。

# 部署 hotfix
[建立 PR、合併、部署]

# 回到功能工作
cd ~/project
# 功能工作未受影響，準備繼續

範例 2：使用 Claude Code 的並行功能開發​

# 設定兩個功能
git worktree add ../project-user-auth feature/user-auth
git worktree add ../project-payments feature/payments

# 終端機 1：使用者認證
cd ~/project-user-auth
claude
您> 實作 OAuth2 認證
[開發認證功能]

# 終端機 2：付款（並行！）
cd ~/project-payments
claude
您> 實作 Stripe 整合
[開發付款功能]

# 兩個功能同時開發！
# 無分支切換，無暫存！

範例 3：Worktree 中的程式碼審查​

# 審查 PR 而不會弄亂主工作區
您> 建立 worktree 以審查 PR #456

Claude：[建立 worktree]
git worktree add ../pr-review-456 origin/pr/456
cd ../pr-review-456

# 使用 Claude Code 審查
您> 審查此 PR 並建議改進

Claude：[審查程式碼]
發現 3 個問題：
1. SQL 注入漏洞
2. 缺少錯誤處理
3. 命名不一致

[Claude 建立 PR 註解或直接修正]

# 審查後清理
git worktree remove ../pr-review-456

使用多代理 Claude Code 的 Worktree​

終極工作流程：Worktree + 多代理​

project/
├── .agents/
├── worktrees/
│   ├── backend/      # 後端代理工作區
│   ├── frontend/     # 前端代理工作區
│   ├── tests/        # 測試代理工作區
│   └── docs/         # 文件代理工作區
└── scripts/
    └── multi-agent-worktree.sh

編排腳本：

#!/bin/bash
# multi-agent-worktree.sh

PROJECT_ROOT=$(pwd)
WORKTREES="$PROJECT_ROOT/worktrees"

# 建立 worktree
git worktree add $WORKTREES/backend origin/main
git worktree add $WORKTREES/frontend origin/main
git worktree add $WORKTREES/tests origin/main
git worktree add $WORKTREES/docs origin/main

# 建立分支
cd $WORKTREES/backend && git checkout -b feature/api-endpoints
cd $WORKTREES/frontend && git checkout -b feature/ui-components
cd $WORKTREES/tests && git checkout -b feature-test-coverage
cd $WORKTREES/docs && git checkout -b feature/api-documentation

# 在它們的 worktree 中啟動代理
gnome-terminal --working-directory=$WORKTREES/backend -- claude &
gnome-terminal --working-directory=$WORKTREES/frontend -- claude &
gnome-terminal --working-directory=$WORKTREES/tests -- claude &
gnome-terminal --working-directory=$WORKTREES/docs -- claude &

echo "✓ 4 個代理已在隔離的 worktree 中啟動！"

好處：

  • 完全隔離
  • 無檔案衝突
  • 獨立的 git 歷史
  • 並行開發
  • 每個 worktree 的 Claude Code 情境

疑難排除​

問題：找不到 Worktree​

您> 開啟 feature-a worktree

Claude：[找不到目錄]
錯誤：../project-feature-a 不存在

解決方案：worktree 已移除或移動。
檢查：git worktree list
如有需要重新建立。

問題：分支已檢出​

錯誤：feature-xyz 已於 ../project-feature-xyz 檢出

解決方案：選擇以下之一：
1. 使用現有的 worktree
2. 先移除現有的 worktree
   git worktree remove ../project-feature-xyz

問題：Detached HEAD​

您> 顯示此 worktree 中的目前分支

Claude：[顯示 detached HEAD]
警告：HEAD 於 abc1234 處 detached

解決方案：這對來自提交的 worktree 是正常的。
如有需要建立分支：
git checkout -b new-branch

✅ 檢查您的理解​

  1. 什麼是 git worktree？

    • 一個分開的 git 儲存庫
    • 同一儲存庫的連結工作目錄
    • 一個 git 分支
    • 一個 stash

  2. 何時應該使用 worktree？

    • 只用於 hotfix
    • 同時在多個分支上工作時
    • 永不，只使用分支
    • 只用於 Claude Code

  3. 如何移除 worktree？

    • 只刪除目錄
    • git worktree remove <路徑>
    • git branch -d <分支>
    • git clean -fd

  4. True or False： Worktree 共用同一個 .git 儲存庫。

    • True
    • False

  5. 為什麼 worktree 對 Claude Code 有好處？

    • 它們沒有好處
    • 每個 Claude Code 工作階段可以有自己的 worktree
    • 只用於 git 操作
    • 它們減少記憶體使用

答案： 1-b, 2-b, 3-b, 4-True, 5-b

總結​

在本課程中，您學到了：

  • 什麼是 worktree - 一個儲存庫的多個工作目錄
  • 建立 worktree - 使用 git 或 Claude Code
  • Claude Code 整合 - 每個工作階段一個 worktree
  • 常見模式 - 功能開發、hotfix、審查
  • 多代理工作流程 - 結合 worktree 與第 14 課
  • 清理 - 移除和修剪 worktree

下一步​

結合 worktree 與：

  • 第 9 課： Git 整合
  • 第 14 課： 多代理自動化
  • 練習： 為您目前的專案建立 worktree

進階閱讀​

掌握 worktree，掌握並行開發！🚀