零基礎 Git Worktree 操作指南

現在很多人會同時開好幾個 AI Agent 幫忙開發，例如一個 Agent 修登入、一個 Agent 改 UI，另一個 Agent 補測試。

問題是如果這些 Agent 都在同一份工作目錄裡操作，就很容易互相覆蓋檔案、改到同一批變更，最後可能額外花時間收拾衝突。

Git Worktree 就可以很好解決這個問題，它可以讓你用同一個專案，同時開出多個資料夾，分別對應不同分支，讓每個 Agent 各做各的，減少互相打架的機率。

今天這篇文章，就想帶你了解 Worktree。

不過開始之前，先確保你對 Git 有一些基本知識哦！例如 Repo、Stash、Branch 等等。

什麼是 Git Worktree

你可以把 Git Worktree 想成：在同一個專案裡，多開幾個不同的工作資料夾。

每個資料夾都可以做自己的功能，你就不用一直切 branch，也不用把改到一半的東西先收起來。

這樣的好處是，你不需要一直 git checkout 來回切 branch，也不需要用 stash 暫存一堆改到一半的內容。

如果你現在是用 AI 協助開發，這個方式特別好用。

因為每個 worktree 都是一個獨立資料夾，你可以想像他們是分給不同 Agent 的獨立工位，每個 Agent 在自己的工位改檔案，就不會互相干擾。

建立 Worktree

建立 Worktree 的方式很簡單。首先，先確保你的電腦有安裝 Git：

• Windows 用戶可以在這邊下載安裝：Git - Install for Windows
• Mac 用戶則在這邊：Git - Install for macOS

接著，到你的專案目錄底下，使用 git worktree add 新增一個 worktree。

比如說你想開一個登入功能的分支：

git worktree add -b feat/login ../feature-login

這個指令會：

• 在目前專案旁邊建立一個 ../feature-login 資料夾
• 建立一個新的 feat/login branch
• 讓這個新資料夾直接 checkout 到 feat/login 分支

下一步，我們就可以到建立好的 worktree 資料夾，安裝依賴後開始開發：

cd ../feature-login
npm install
npm run dev

如果你的 branch 本來就已經存在，也可以不用 -b，直接這樣寫：

git worktree add ../feature-login feat/login

這邊有兩個注意事項：

1. 同一個 branch 通常不能同時被 checkout 到多個 worktree。
2. 每個 worktree 都是獨立資料夾，所以 node_modules、建置產物、開發中的暫存檔案，也都會各自存在自己的目錄裡

查看 Worktree

有時候 worktree 開多了，很容易忘記自己到底開了哪些。

這時候就可以用 git worktree list 查看目前所有 worktree：

git worktree list

輸出可能會長這樣：

/path/repo            abc123 [main]
/path/feature-login   def456 [feat/login]

你可以從這個列表快速看出：

• worktree 在哪個路徑
• 它目前對應哪個 branch
• 目前指向哪個 commit

移除 Worktree

當功能做完、合併回主分支後，就可以把不需要的 worktree 移除：

git worktree remove ../feature-login

這個動作是移除那個工作目錄，不是刪掉整個 repository。

不過如果裡面還有未提交的變更，Git 會阻止你刪除，所以刪之前記得先確認內容是否已經提交或不需要保留。

或是你也可以使用 --force 來強制刪除：

git worktree remove --force ../feature-login

移動 Worktree

如果你只是覺得原本 worktree 的資料夾位置不順手，也可以直接把它移到別的地方，不用刪掉重建。

例如原本你把登入功能的 worktree 建在：

../feature-login

後來你想把它集中放到 ../worktrees 資料夾底下，就可以用：

git worktree move ../feature-login ../worktrees/feature-login

這個指令的意思是：

• 把 worktree 的目錄從舊位置移到新位置
• Git 也會同步更新內部記錄
• 你不用重新 checkout branch，也不用重新建立 worktree

實務上很適合拿來整理目錄結構。

比如一開始只是臨時測試，後來發現 worktree 越開越多，就可以把它們統一搬到像 ../worktrees/ 這種集中管理的資料夾裡。

補充知識

不過為什麼新開出來的資料夾也能正常版控呢？它明明不是一份完整複製的 Repo？

原因是 worktree 資料夾裡的 .git 通常不是資料夾，而是一個「檔案」。例如：

gitdir: /Users/you/project/.git/worktrees/feature-login

這一行代表目前這個 worktree 的 Git 管理資訊，實際上放在原始 repository 裡的 .git/worktrees/... 下面。

所以 worktree 不只是單純複製一份 repo，而是讓我們用節省空間的方式，共用 .git。

總結

如果你會同時開多個 AI Agent 做不同功能，Git Worktree 是很值得學會的工具。

它可以讓你在同一個 repository 下，同時開多個獨立工作目錄，讓每個 Agent 各自在自己的 branch 與資料夾中工作，減少互相覆蓋檔案、切 branch 混亂、或一堆 stash 的問題。