為什麼 AI Agent 要使用 Git Worktree？

 

Worktree 是 AI Agent 的安全工作環境

當你請 AI Agent 修改程式、做實驗、重構資料夾或產生新功能時，它需要一個可以放心嘗試的地方。Git Worktree 的用途，就是讓同一個 Git 專案同時開出多個資料夾：一個保留穩定版本，另一個讓 AI Agent 做實驗。這樣就不用備份整個專案，也不用擔心 AI 一邊嘗試、一邊把原本可用的版本弄亂。

你可以把它想成：Git 是專案的版本紀錄本，branch （分支）就像是不同想法的頁籤（特色分支），worktree 則是把某個頁籤拿出來變成獨立資料夾。AI Agent 在不同資料夾上做事，最後你再決定要不要把成果合併回主要工作的資料夾（main 分支）。

情境	不用 Worktree 的風險	使用 Worktree 的好處
讓 AI Agent 試做新功能	原本可用版本可能被改壞	實驗資料夾和穩定資料夾分開
同時請兩個 Agent 做不同方案	兩邊改到同一批檔案，容易混在一起	每個方案各自有工作區與分支
需要比較修改前後	只能靠記憶或反覆切換分支	兩個資料夾可直接並排比較
實驗失敗想放棄	要小心還原檔案	確認不保留成果後，移除 worktree，再刪除實驗分支

Git 是什麼？為什麼需要 Git？

Git 是一套版本控制工具。它會記錄專案在不同時間點的樣子，讓你知道誰改了什麼、何時改、為什麼改。如果改壞了，可以回到之前的版本；如果有不同想法，也可以開分支各自發展。

• commit：把目前狀態存成一個版本快照。
• branch：讓一條修改路線獨立發展，例如 main 是穩定主線，feature 分支是新功能實驗。
• merge：把某個分支的成果合併回另一個分支。
• reset：把目前分支退回指定版本。這個動作可能丟掉後續修改，使用前要確認。
• worktree：把同一個 Git 專案的不同分支，放到不同資料夾中同時工作。

Git Worktree 的概念圖

圖解：這張圖整理 worktree 的核心概念，main 保持穩定，新的 worktree 則提供 AI Agent 獨立實驗空間。

圖 1：main 保留穩定版本，proj1-v2 讓 AI Agent 在另一個資料夾做實驗。

什麼時候要讓 AI Agent 使用 Worktree？

• 你要它一次做比較大的修改，例如重構、換框架、加入登入流程、整理資料結構。
• 你想同時比較兩種以上方案，例如 A 方案重視速度、B 方案重視可讀性。
• 你要它修 bug，但不希望它影響目前可展示或可交付的版本。
• 你想在 Agent 做事時，自己仍然能打開原本資料夾查看或執行專案。
• 你要保留清楚的實驗紀錄，之後可以決定合併、放棄或交給另一個 Agent 接手。

如果只是改一行文字、補一個小註解或調整 README，通常不需要 worktree。Worktree 適合用在「改動範圍不小、可能要比較、可能會反悔」的工作。

安裝 Git

在 Windows 上可使用 PowerShell 搭配 winget 安裝 Git。打開 PowerShell 後輸入：

winget install --id Git.Git -e --source winget

安裝完成後，重新開啟終端機，再輸入以下指令確認是否安裝成功，這個指令是檢查 Git 的安裝版本：

git --version

如果系統找不到 winget，也可以前往 Git 官方 Windows 下載頁安裝：https://git-scm.com/download/win

註：winget 是 Windows Package Manager 的命令列工具，可用來搜尋、安裝、更新與移除軟體。它適用於 Windows 11 與較新的 Windows 10，通常會隨 App Installer 提供。

從一個小專案開始

如果是這台電腦上第一次使用 Git，請先輸入以下指令：

git config --global user.name "你的名字"
git config --global user.email "你的 Email"

可以使用以下指令查閱設定是否正確：

git config --global user.name 
git config --global user.email 

1. 建立專案與第一個檔案

本範例使用 Visual Studio Code 進行編輯，先建立一個資料夾 proj1，裡面放 src\index.html。這個檔案代表我們的第一版網頁內容。

<h1>Hello</h1>

操作結果：建立 proj1\src\index.html 後，專案已具備可交給 Git 管理的基本檔案結構。

圖 2：在檔案總管或 VS Code 中建立 proj1\src\index.html。

2. 初始化 Git 並建立第一個 commit

在包含 proj1 的上層資料夾中開啟 PowerShell；本文範例位置是 C:\Labs\gworktree。接著依序輸入以下指令，進入專案、初始化 Git，並確認目前的 worktree。剛開始只有主工作區。

cd .\proj1
git init -b main
git worktree list

指令結果1：成功建立 Git 本地端儲存庫以及 main 分支。

圖 3：終端機執行狀態。

指令結果2：執行 git init 後，資料夾中會出現 .git，代表這個資料夾已經成為 Git 專案。

圖 4：在檔案總管可以看到 .git 資料夾。

接著把檔案加入版本紀錄並建立第一個 commit：這項全域設定通常只需完成一次，之後即可正常建立 commit。

git add .
git status
git commit -m "初次 commit"

指令結果：執行 git add 與 git commit 後，Git 會建立第一個版本紀錄，作為後續比較與回復的基準點。

圖 5：建立第一個 commit 後，Git 已經記住初始版本。

3. 新增一個 worktree 當作實驗區

現在建立新 worktree 資料夾 proj1-v2，並同時建立新分支 feature-v2。新的版本可以在這個資料夾工作，不會直接動到 main 分支 (../Proj1) 的檔案。

git worktree add ../proj1-v2 -b feature-v2
git worktree list

指令結果：執行 git worktree add 後，Git 會建立 proj1-v2 資料夾，並將它連到新的 feature-v2 分支。

圖 6：Git 建立 proj1-v2，並把它連到新分支 feature-v2。

指令結果：再次執行 git worktree list，在檔案總管可以看到同一個專案目前同時存在 proj1 與 proj1-v2 兩個工作區。

圖 7：同一個專案現在有兩個資料夾：proj1 與 proj1-v2。

4. 在實驗區修改內容並提交

打開 proj1-v2\src\index.html，把內容改成第二版。此時 proj1 的 index.html 仍是 Hello，proj1-v2 則是 Hello v2。這就是 worktree 最直觀的價值：兩個資料夾可以同時存在不同版本。

<h1>Hello v2</h1>

操作結果：修改 proj1-v2 裡的 index.html 後，主工作區 proj1 仍保持原內容，兩邊可直接比較差異。

圖 8：左右兩邊的 index.html 內容不同，可直接比較。

接著在同一個 PowerShell 中，從 proj1 切換到 proj1-v2，再提交這次修改：

cd ../proj1-v2
git add .
git status
git commit -m "v2"
git log --oneline

指令結果：在 proj1-v2 中提交 v2 commit 後，實驗分支已保存修改成果。執行 git log --oneline 後，可以確認目前分支已有 v2 commit 與初次 commit 兩筆紀錄。

圖 9：在 proj1-v2 分支建立 v2 commit。

5. 回到 main分支，把實驗成果合併回來

如果你確認實驗結果可以採用，就在同一個 PowerShell 中切回 proj1，確認 main 的紀錄，再合併 feature-v2。

cd ../proj1
git checkout main
git log --oneline

指令結果：切回 main 後查看紀錄，可看到主線仍停在初次 commit，尚未受到實驗分支影響。

圖 10：回到 main 後，主線仍停在初次 commit。

合併 feature-v2 分支，並檢查紀錄：

git merge feature-v2
git log --oneline

指令結果：執行 git merge feature-v2 後，main 分支會取得實驗分支的修改內容。

圖 11：merge 後，main 取得 v2 的修改。

操作結果：合併完成後，主工作區的 index.html 也會呈現 Hello v2，表示修改已進入 main。

圖 12：合併後，主工作區也變成 Hello v2。

Merge 後如果反悔怎麼辦？

如果剛合併就發現不想要，而且這次變更尚未推送或分享，可以把 main 分支往前退一個 commit。git reset --hard 會改寫目前分支，並捨棄已追蹤檔案的未提交修改；執行前應先請 AI Agent 說明受影響的檔案並確認工作區乾淨。

git reset --hard HEAD~1

指令結果：執行 git reset --hard HEAD~1 會讓目前分支回到前一個 commit，僅適合尚未推送或分享的本機版本。

圖 13：HEAD~1 代表目前版本的前一個 commit。

如果要退到更早的指定版本，先查 log，複製目標 commit id，再 reset 到那個 id。

git log --oneline
git reset --hard 58b46a9

指令結果：使用指定 commit id 執行 reset，可以精準回到某一個歷史版本。

圖 14：使用 commit id 可退回指定版本。

這時候 ./proj1/src/index.html 就會還原到：

<h1>Hello</h1>

注意：

reset --hard 也會捨棄已追蹤檔案的未提交修改。若 main分支已經推送或與他人共用，不要用 reset 改寫歷史；應優先使用 git revert 建立一筆反向 commit。

git revert <commit-id>

若不確定該回復哪一筆 commit，使用git log列出目前工作區狀態與可能影響，確認後再執行。

6. 任務完成後收拾 worktree

確認要採用實驗成果時，可以再次合併；確認不再需要實驗區後，移除 worktree，再刪掉對應分支。這裡我們再度合併feature-v2分支。

git merge feature-v2
git worktree remove ../proj1-v2
git branch -d feature-v2
git worktree list

指令結果：完成 merge、worktree remove 與 branch -d 後，實驗工作區與分支都已清理，只留下 main。

圖 15：合併、移除 worktree、刪除實驗分支，最後只留下 main。

操作結果：在移除 worktree 之前，檔案總管中仍可看到 proj1-v2 資料夾。

圖 16：收拾前，檔案總管仍可看到 proj1-v2。

操作結果：移除 worktree 後，proj1-v2 資料夾消失，表示實驗工作區已收拾完成。

圖 17：移除後，proj1-v2 資料夾不再存在。

怎麼請 AI Agent 使用 Worktree？

上面的範例目的是讓你透過手動過程了解 Git Worktree 的運作原理，當你理解這個原理的時候，你才能夠準確地知道所下的提示詞會產生甚麼結果，以下列表幾個使用情境的提示詞範例僅供參考，使用 AI Agent 時，不只要下指令，也要講清楚限制、風險與完成條件。以下提示可以直接複製後依照專案名稱替換。

使用情境	提示範例
建立安全實驗區	請先不要修改 main 工作區。請用 Git Worktree 建立一個新的工作區與分支，分支名稱為 feature/login-demo。完成後列出目前 worktree，並說明你接下來會在哪個資料夾修改。
大改前先規劃	我想請你重構這個專案，但我沒有程式背景。請先建立 worktree，再用一般人看得懂的方式列出修改計畫、可能風險、驗收方式。等我確認後再動手。
比較兩個方案	請用兩個不同 worktree 分別做 A/B 方案：A 方案優先簡單、B 方案優先可維護。完成後請整理差異、測試結果與你建議採用哪一個。
合併前檢查	在 merge 回 main 前，請先檢查 git status、git log --oneline、修改檔案清單與測試結果。若有任何未提交或衝突，先停下來說明。
安全反悔	我想撤回剛才的 merge。請先解釋 git reset --hard 會造成什麼影響，列出目前 commit，再建議最安全的復原方式。不要直接執行危險指令，等我確認。

給初學者的安全檢查表

• 改動前先確認：AI Agent 目前在哪個資料夾？在哪個分支？
• 每次重要修改後，請 Agent 執行 git status，確認沒有意外檔案。
• 要求 Agent 把每個 commit 訊息寫清楚，日後才知道每一步在做什麼。
• merge 前先看 git log --oneline，確認要合併的是正確分支。
• 看到 reset --hard、clean、delete、remove 這類字眼時，先請 Agent 解釋影響再執行。
• 任務完成後移除不用的 worktree，避免日後忘記哪個資料夾才是正式版本。

一分鐘記住 Git Worktree

Git Worktree 不是進階工程師才需要的工具；對 AI Agent 使用者來說，它更像是一個安全工作流程。當你把穩定版本和實驗版本分開，AI Agent 就能更大膽地嘗試，你也能更清楚地檢查、比較、合併或放棄。

最實用的判斷方式是：只要你心裡出現「如果 AI 改壞了怎麼辦？」這個問題，就值得考慮先建立 Worktree。

更多學習資源：

除了本地 Git 之外，GitHub也是與程式版本控制，多人協作的重要工具，若想更完整學習 Git 與 GitHub 的觀念與實務操作，包含版本控制流程、分支協作、遠端儲存庫管理，以及團隊開發時常見的 GitHub 協作方式，建議可以進一步參考：

【GH900】Git版本控制與GitHub協作入門

參考資料

以下是參考資料列表：

• Git Worktree 官方文件
• Microsoft WinGet 官方文件