Claude Code 同名 worktree 再開一次:續用舊進度,還是悄悄重設到預設分支,worktree.baseRef 怎麼選
claude --worktree feature-auth 這一行,第一次跑和第二次跑,不保證是同一種結果。第一次它建一個新的 worktree;第二次名字已經存在,目錄照樣會打開,但打開的位置不一定是你上次離開的地方。
拿一個設想的處境來看(不是我的親身經歷):週五下班前,你讓 Claude 在這個 worktree 裡改了一半登入流程,週一早上照同一行指令再開一次。目錄在,分支名字也對,疑問是這到底是接著週五的位置,還是 Claude Code 趁你不在換了起點。
兩種答案都有可能,要看當下的條件。
官方文件怎麼說
預設行為很單純。文件的 “Reuse a worktree name” 那一段寫:「If a worktree with the name you pass to --worktree already exists, Claude Code opens it instead of creating a new one.」同名就是打開既有的,不是另建一個。
麻煩在後面那一句。文件接著說,在預設的 "fresh" base 下,重開的 worktree 有可能被重設到 repository 的預設分支,而不是停在原本的 tip,而且是在「以下條件全部成立」時。我把四個條件照文件順序列出來:
1 | 1. sandbox 沒有限制你這個 session 的檔案寫入, |
四條缺任何一條,就不重設。文件另外還列了幾種一律停在舊 tip 的情況:Claude Code 無法確認 worktree 的狀態、worktree.baseRef 設成 "head"、傳進來的名字是 pull request 或 merge request 的參照。
第 4 條裡「PR 已合併」的判斷,文件說得很明白:只看 git 狀態,不去問 GitHub 或 GitLab。條件是遠端分支已經不存在,而且 worktree 裡每一個 commit 都已經在預設分支上。
把四個條件疊起來看
四條一起讀,會被重設的 worktree 長這樣:沒開 sandbox、乾淨、還在原分支上,而且要嘛沒有自己的 commit,要嘛 PR 已合併、遠端分支也刪了。前一種沒有任何你寫過的東西,後一種的 commit 早就在預設分支上,被換掉的都只是出發點。這一段是我自己的推論,文件沒有這樣總結。
所以我的立場是這樣:同名 worktree 當「工作區的名字」用沒問題,當「存檔格」用就會有落差。週五的進度如果要活到週一,靠的是 commit,因為只要 worktree 上有自己的 commit、PR 又還沒合併,第 4 條就不成立,它會停在舊 tip。只改了檔案沒提交,第 2 條不成立,也不會被重設。真正會被重設的,是你以為「我之前在這裡做過事」、實際上什麼都沒留下(或東西早就進了預設分支)的那種 worktree。
什麼情況下我會改這個想法:如果有人實際重現出「有未提交的變更仍被重設」,那文件寫的條件就不夠完整,這段整個要重寫。我沒有做過這個實驗,所以現在只是照文件推。
sandbox 讓同一個專案在兩台機器上不一樣
第 1 條容易被忽略。它的意思是,只要你這個 session 的 sandbox 限制了檔案寫入,或設定檔裡啟用了 sandbox,這個重設就不會發生,worktree 會停在舊 tip。同一個專案、同一行指令,A 機器有開 sandbox、B 機器沒開,兩邊的行為可能不一樣。
「限制檔案寫入」在文件裡的精確定義,我沒有讀到展開的說明,這裡不多猜。
文件對這種情況給了一個處方:用 sandbox 又想從最新的預設分支開始,就先 git fetch origin,然後給 --worktree 一個新名字。換名字是最不需要記條件的做法,因為新名字根本沒有「重開」這回事。
worktree.baseRef 管的是新 worktree 從哪裡長出來
前面講的是重開。worktree.baseRef 管的是更早的一步:新建 worktree 時,分支從哪裡起算。
1 | { |
這是官方文件的最小範例,效果是每個新 worktree 都從你目前本機的 HEAD 開。它有兩個值。預設的 "fresh" 從遠端的預設分支(通常是 main)開,起點乾淨、和遠端一致;"head" 從本機 HEAD 開,會帶著你還沒 push 的 commit 和 feature 分支的狀態。文件特別註明,不能把它設成某個分支名;要從特定的既有分支開,得自己用 git 先建好。
changelog 裡這個設定是 2.1.133 加進來的,同一行還有一個註記:預設的 fresh 把 EnterWorktree 的 base 改回 origin/<default>,在那之前(2.1.128 起)它是本機 HEAD;想在新 worktree 裡保留未推送的 commit,要設 worktree.baseRef: "head"。如果你的 worktree 行為在某次升級後變了,這一行是第一個該對照的地方。
兩個值怎麼選,我的取捨很簡單:預設用 fresh,只有真的需要「帶著還沒推的東西開新 worktree」才改 head。代價是 head 失去了「起點等於遠端」的保證,而且依前面列的例外,head 下重開同名 worktree 一律停在舊 tip,不會重設。
fresh 還有幾個文件寫明的細節:超過 24 小時沒 fetch 時,它會去抓預設分支,最多等五秒,抓失敗就用本機快取的 ref;如果 git 或 ssh 會跳出密碼、passphrase 或新主機確認,這次 fetch 就算失敗,不會等你輸入。沒有設定 remote,或 origin/HEAD 抓不到,就退回你目前的本機 HEAD。
另外,子代理的 worktree 與 --worktree 用同一個 base,所以預設也是從預設分支開,除非設成 "head"。
這篇我只讀了官方 worktrees 文件與 changelog,沒有實際操作。四個重設條件、清理規則都是「文件這樣寫」,我沒有在自己的機器上重現過重設。changelog 的 2.1.208 已經出現「reused worktree names reset to the current base」這句,但它寫在 Agent view 的脈絡裡;四個條件各自從哪一版起算,changelog 沒有逐版列出,我不寫。
離開的時候
重開的問題講完,還有結束時的清理,因為它決定了「週一還有沒有東西可以重開」。
文件的規則分三種。worktree 是乾淨的:沒命名的 session,Claude 自動把 worktree 和分支刪掉;命名過的 session 會先問你,讓你選擇留著。worktree 裡有東西:Claude 問你要留還是刪。留下會保留目錄與分支,要回去就用結束時印出來的 claude --worktree <name> --resume;刪掉則連目錄、分支與裡面所有的工作一起刪。狀態無法確認,例如算不出變更數量,或看不了 submodule 的 checkout:同樣是問你,不自動刪。
我過去寫過一篇 Git Worktrees 完整教學,清理那段只寫了「沒修改自動刪、有修改問你」。照這次讀到的文件,乾淨但有命名的 session 也會先問,那一篇是少了這個條件,算是補充。
有兩種情況不會有這個提問。用 -p 跑的非互動執行沒有退出提示,所以 Claude 不清理,它建立時上的鎖也留著,直到之後某個 session 的 stale-lock 清掃才放掉。要自己刪,用 git worktree remove,被 git 拒絕說已鎖定,就先 git worktree unlock。子代理與背景 session 的 worktree 則由定期清掃處理,超過 cleanupPeriodDays 的才會被移除,而且仍有未提交檔案或未推送 commit 的、你自己用 git worktree add 建的、以及沒背景化的 --worktree session,一律保留。
最後一個容易嚇到人的訊息。如果重開時看到 belongs to a different repository 或 is a leftover worktree,文件說兩者都代表 git 把那個名字對應的目錄綁在別的位置,複製或搬動專案後會發生。解法是換一個名字。
回到週一早上那個問題。如果週五你把東西 commit 了、PR 也還沒合併,重開是接著走;如果你只是改了幾個檔,沒提交,它同樣不會被重設;真正會悄悄換起點的,是什麼都沒留下的空 worktree,或東西早已合併進預設分支的那個。週五離開前跑一次 git -C .claude/worktrees/feature-auth status,就能知道它是乾淨的還是有東西,再決定要不要先 commit。


















