Git Worktree：同時在多個分支工作的正確姿勢

你是否有過這樣的經歷：正在 feature/new-dashboard 分支埋頭開發，突然來了一個緊急 bug 要修。你必須 git stash、切換到 main、修 bug、commit、切回去、git stash pop——整個過程繁瑣且容易出錯，更別說有時 stash 彈回來還會有衝突。

Git Worktree 是解決這個痛點的完美工具，卻常常被開發者忽略。

什麼是 Git Worktree？

通常一個 Git repository 只有一個工作目錄（working tree），你需要切換分支才能在不同分支上工作。Worktree 讓你可以同時 checkout 多個分支到不同的目錄，共用同一個 .git 資料夾。

專案根目錄/
├── .git/          ← 共用的 git 資料
├── src/           ← 主要工作目錄（main 分支）
│
../project-hotfix/ ← 另一個工作目錄（hotfix/login-bug）
../project-feat/   ← 另一個工作目錄（feature/dashboard）

基本操作

建立新的 Worktree

# 從現有分支建立 worktree
git worktree add ../hotfix hotfix/login-bug

# 同時建立新分支
git worktree add -b feature/new-api ../new-api main

# 查看所有 worktree
git worktree list
# /Users/dev/myproject         abc1234 [main]
# /Users/dev/hotfix            def5678 [hotfix/login-bug]
# /Users/dev/new-api           ghi9012 [feature/new-api]

刪除 Worktree

# 先刪除目錄（或手動刪除）
git worktree remove ../hotfix

# 強制刪除有未提交變更的 worktree
git worktree remove --force ../hotfix

# 清理已不存在的 worktree 記錄
git worktree prune

實際工作流程

場景一：緊急 hotfix

# 目前在 feature/dashboard 開發中
# 不需要 stash！直接開新 worktree

git worktree add /tmp/hotfix-login hotfix/login-bug
cd /tmp/hotfix-login

# 修復 bug
vim src/auth/login.ts
git commit -am "fix: resolve session timeout issue on mobile"
git push origin hotfix/login-bug

# 修完了，回到原本的工作
cd ~/projects/myproject
# feature/dashboard 的狀態完全沒被打擾

# 清理
git worktree remove /tmp/hotfix-login

場景二：比較兩個分支的行為

# 建立兩個 worktree 分別在不同分支
git worktree add ../v2-testing v2-performance-refactor

# 在一個終端機跑舊版
cd ~/project && npm run dev -- --port 3000

# 在另一個終端機跑新版
cd ~/project-v2-testing && npm run dev -- --port 3001

# 可以同時打開兩個瀏覽器視窗對比

場景三：平行執行長時間任務

# 在主分支跑測試
cd ~/project && npm test &

# 同時在 feature 分支繼續開發
cd ~/project-feature && code .

搭配 tmux 的工作流

# .bashrc 或 .zshrc 中的輔助函式
function gwt() {
  local branch=$1
  local worktree_path="/tmp/wt-${branch//\//-}"

  git worktree add "$worktree_path" "$branch" 2>/dev/null || \
  git worktree add -b "$branch" "$worktree_path" HEAD

  # 如果有 tmux，在新視窗中開啟
  if [ -n "$TMUX" ]; then
    tmux new-window -c "$worktree_path" -n "$branch"
  else
    cd "$worktree_path"
  fi
}

# 使用：gwt feature/user-settings

注意事項

1. 同一分支不能同時在多個 worktree

# 錯誤：main 分支已在主目錄 checkout
git worktree add ../another-main main
# fatal: 'main' is already checked out at '/Users/dev/project'

2. 每個 worktree 有獨立的 HEAD 和索引

在一個 worktree 的 git status 不會顯示其他 worktree 的改動，它們是完全獨立的工作環境。

3. Node.js 的 node_modules 問題

每個 worktree 共用 .git，但 node_modules 預設是獨立的。如果空間有限，可以使用 symlink：

# 建立 worktree 後，將 node_modules 連結到主目錄
cd /tmp/wt-feature
ln -s ~/project/node_modules ./node_modules

但要注意這樣做如果兩個分支的依賴版本不同，可能會有問題。較好的做法是使用 pnpm 的 --shared-workspace-lockfile。

4. 設定檔路徑問題

如果你的應用程式使用相對路徑讀取設定檔，在不同 worktree 中路徑可能不同，需要注意。

Bare Repository 的進階玩法

搭配 bare repository，可以建立更整潔的 worktree 管理結構：

# Clone 成 bare repository
git clone --bare https://github.com/user/repo.git repo.git
cd repo.git

# 建立工作目錄（不直接在 bare repo 中工作）
git worktree add ../repo-main main
git worktree add ../repo-feature feature/new-ui

# 目錄結構
# repo.git/           ← bare repo（只有 git 資料）
# repo-main/          ← main 分支的工作目錄
# repo-feature/       ← feature 分支的工作目錄

與其他工具的比較

方法	操作複雜度	磁碟用量	可同時工作
git stash + 切換分支	中	低	否
Clone 第二份	低	高（完整複製）	是
Git Worktree	低	低（共用 .git）	是

小結

Git Worktree 是一個低調但非常實用的 Git 功能。只需幾個指令，就能在不打擾現有工作的情況下切換到另一個分支工作。對於需要頻繁處理緊急 hotfix、或想要平行開發多個功能的工程師，Worktree 絕對值得納入你的日常工作流程。