Worktree 與多任務隔離

返回 Codex 教學總目錄

目標與準備

本段提到的教學與資源: 分支與差異

Worktree 是同一 Git 儲存庫的另一份 checkout：檔案與暫存區分開，提交與分支資料仍共用。它適合一邊修 Bug、一邊研究其他功能，但不是安全沙盒。兩個目錄若連到同一資料庫、同一雲端文件或相同 port，仍可能互相影響。多人任務要同時分清檔案範圍、外部資料與執行服務，不能只看資料夾名稱不同就認定完全隔離。

步驟 1：建立不含私人資料的練習庫

在自己的練習資料夾裡，用檔案管理員新增空白的 worktree-lab 資料夾。Windows 用檔案總管，macOS 用 Finder，Linux 用檔案管理員；再於該資料夾開啟終端機。先確認現在的路徑確實是新資料夾，沒有正式專案檔案。下列命令只在這個新練習庫執行，設定作者身分也是此庫的 local 設定，不要加 --global。

git init -b main
git config user.name "Codex Learner"
git config user.email "learner@example.test"
git status --short

用編輯器在 worktree-lab 新增 notes.md，完整內容如下。這裡的 marker 是刻意可辨識的練習值，讓你不用依賴 Codex 的敘述就能比對檔案。保存 UTF-8 純文字並確認檔名沒有多出 .txt，再執行下一段提交命令。這次只加入 notes.md，不用 git add .，以免不小心把旁邊其他檔案也收進練習提交。

# Worktree practice

Marker: LOCAL-A

git add -- notes.md
git commit -m "Add worktree practice baseline"
git status --short
git branch --show-current

預期目前分支是 main，status 沒有未提交列。若提交失敗，讀取錯誤並修正此練習庫的作者設定；不要為了完成教材改公司儲存庫的簽章政策。還沒有第一個提交時，沒有可用的 HEAD 基準，先完成此步再新增 worktree。已有同名資料夾或分支時換一組未使用的練習名稱，將後續命令一致替換，不強制覆蓋既有內容。

步驟 2：建立第二個 checkout

git worktree add -b codex/worktree-practice ../worktree-copy
git worktree list

命令在目前資料夾外的同一層建立 worktree-copy，並用新分支 codex/worktree-practice。執行前先確認該路徑不存在；list 應列出兩個實際路徑，分別對應 main 與新分支。兩份 notes.md 一開始都應是 LOCAL-A。Windows 路徑也可以用這段相對路徑，前提是終端機確實在 worktree-lab；不確定時用終端機與路徑的方法先核對。

用另一個編輯器視窗開啟 worktree-copy/notes.md，只將 LOCAL-A 改成 COPY-B。回到原本 worktree-lab 的視窗，確認自己的 notes.md 仍是 LOCAL-A，再查看兩邊 status 與差異。不要在兩個視窗都只看檔案標籤 notes.md；顯示完整路徑或根目錄名稱，才能知道目前正在修改哪一份。

git status --short
git -C ../worktree-copy status --short
git -C ../worktree-copy diff -- notes.md

預期第一行 status 沒有改動，第二個 status 顯示 notes.md 已修改，diff 只有 marker 一行變動。這證明工作檔案隔離，不表示修改已合併回 main。若兩邊都變了，先核對實際路徑，看看是不是兩個編輯器指向同一個資料夾，或你也手動改了另一份；不要繼續提交直到原因清楚。

步驟 3：認識分支占用與保存成果

git -C ../worktree-copy switch main

Git 正常會拒絕把同一分支同時 checkout 到兩個 worktree，錯誤會指出 main 已被另一個 worktree 使用。這個失敗是保護機制，兩邊仍應留在原分支；不要加忽略占用或強制選項。回到自己的副本分支，把已核對的 marker 修改提交，再從原目錄比較兩個分支。提交仍保存在同一個本機儲存庫，不會自動出現在 GitHub。

提交前再做一次移除失敗的對照。保持 COPY-B 尚未提交，先用 worktree list 核對 ../worktree-copy 的完整路徑確實是本篇副本，再執行下面命令。預期 Git 因修改尚未保存而拒絕，資料夾與 COPY-B 都仍在。若已先提交，就跳過這個對照，不再製造額外變更。確認後才執行下一段提交；不用 --force。

git worktree list
git worktree remove ../worktree-copy
git -C ../worktree-copy status --short

git -C ../worktree-copy add -- notes.md
git -C ../worktree-copy commit -m "Change isolated practice marker"
git -C ../worktree-copy status --short
git diff main...codex/worktree-practice -- notes.md

Codex 桌面版怎麼對應這個流程

在 Git 專案的新任務輸入框下選 Worktree，再選起始分支，送出需求後由 Codex 建立工作目錄。選目前分支連同未提交修改時，先核對那些修改確實應帶入，不要把無關私有資料也當作任務背景。桌面建立的管理型 worktree 預設可能是 detached HEAD；要長期保留成果，可在任務標頭用 Create branch here 建立分支，再按正常 Git 流程驗收提交。

需要把同一任務與程式帶到 Local 時用 Hand off，完成後重新核對目錄、分支及檔案；Handoff 是移動工作，不等於已合併 main 或已部署。Windows、macOS、Linux 依可用的桌面版本操作相同欄位；若 Linux 預覽沒有所需控制，使用本篇 Git 命令方式並標記差異。手機透過 Remote 控制連線電腦上的任務，worktree 留在主機，不是在 iPhone 或 Android 本機執行 Git。

常見問題、清理與驗收

副本缺少環境設定時，先看 .gitignore 與 README，依專案自己的準備步驟建立練習設定。不要把正式 .env 整份複製過去當捷徑。Codex 管理型本機 worktree 的 .worktreeinclude 有特定複製規則，不能套用到本篇手動 Git worktree；需要它時查官方文件及資料安全。預覽 port 被占用就選另一個本機 port 並記錄網址，不停止別人的服務。

清理前關閉正在使用副本的編輯器、終端機或預覽程序，回到原 worktree-lab，執行 list 比對完整目標路徑，再確認副本 status 為空。這次成果已提交在 codex/worktree-practice 分支才可移除副本；若還有未提交檔案，先保存與核對，遇到拒絕時不加 --force。下列操作只移除本篇建立的 worktree-copy，保留原庫與已提交分支。

git worktree list
git -C ../worktree-copy status --short
git worktree remove ../worktree-copy
git worktree list
git show codex/worktree-practice:notes.md

驗收時 list 應只剩原目錄，main 的 notes.md 仍是 LOCAL-A，git show 仍能看到分支中的 COPY-B。再加上先前一邊乾淨、一邊修改與分支占用失敗的紀錄，才足以證明建立、隔離、保存、移除四個階段。Git 命令的本機參考驗證與 Codex 桌面 Handoff 要分開標示；未操作平台依官方文件查證。下一步讀子代理分工，比較目錄隔離與工作分工各自解決什麼問題。

返回 Codex 教學總目錄

閱讀完整文字說明

Repository to Worktree A / B to Integration

• AI 工具
• 教學
• Codex