> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 worktrees 執行平行會話

> 在獨立的 git worktrees 中隔離平行的 Claude Code 會話，使變更不會相互衝突。涵蓋 `--worktree` 旗標、子代理隔離、`.worktreeinclude`、清理和非 git VCS hooks。

[git worktree](https://git-scm.com/docs/git-worktree) 是一個獨立的工作目錄，具有自己的檔案和分支，但與主要檢出共享相同的儲存庫歷史記錄和遠端。在自己的 worktree 中執行每個 Claude Code 會話意味著一個會話中的編輯永遠不會觸及另一個會話中的檔案，因此您可以讓 Claude 在一個終端中建置功能，同時在第二個終端中修復錯誤。

本頁涵蓋 CLI 中的 worktree 隔離。下面的所有內容都假設使用 git 儲存庫。對於其他版本控制系統，請參閱[非 git 版本控制](#non-git-version-control)。[桌面應用程式](/zh-TW/desktop#work-in-parallel-with-sessions)會自動為每個新會話建立一個 worktree。

Worktrees 是執行 Claude 平行處理的幾種方式之一。它們隔離檔案編輯，而[子代理](/zh-TW/sub-agents)和[代理團隊](/zh-TW/agent-teams)協調工作本身。請參閱[平行執行代理](/zh-TW/agents)以比較這些方法，或跳到[使用 worktrees 隔離子代理](#isolate-subagents-with-worktrees)以同時使用 worktrees 和子代理。

<h2 id="start-claude-in-a-worktree">
  在 worktree 中啟動 Claude
</h2>

傳遞 `--worktree` 或 `-w` 以建立隔離的 worktree 並在其中啟動 Claude。預設情況下，worktree 在您的儲存庫根目錄下的 `.claude/worktrees/<value>/` 下建立，在名為 `worktree-<value>` 的新分支上：

```bash theme={null}
claude --worktree feature-auth
```

要將 worktrees 放在其他地方，請配置 [`WorktreeCreate` hook](#non-git-version-control)。在另一個終端中使用不同的名稱再次執行該命令以啟動第二個隔離的會話：

```bash theme={null}
claude --worktree bugfix-123
```

如果您省略名稱，Claude 會生成一個名稱，例如 `bright-running-fox`：

```bash theme={null}
claude --worktree
```

您也可以在會話期間要求 Claude「在 worktree 中工作」，它將使用 [`EnterWorktree`](/zh-TW/tools-reference) 工具建立一個。進入 worktree 後，Claude 可以透過呼叫 `EnterWorktree` 並指定目標路徑，直接切換到 `.claude/worktrees/` 下的另一個 worktree。前一個 worktree 保持在磁碟上未被觸及。

在第一次在目錄中使用 `--worktree` 之前，請透過在該目錄中執行一次 `claude` 來接受工作區信任對話。如果尚未接受信任，`--worktree` 將以錯誤退出並提示您先在目錄中執行 `claude`。非互動式執行搭配 `-p` 會跳過[信任檢查](/zh-TW/security)，因此 `claude -p --worktree` 會在沒有信任檢查的情況下進行。

<Tip>
  將 `.claude/worktrees/` 新增到您的 `.gitignore`，以便 worktree 內容不會在您的主要檢出中顯示為未追蹤的檔案。
</Tip>

<h3 id="choose-the-base-branch">
  選擇基礎分支
</h3>

Worktrees 從您的儲存庫的預設分支 `origin/HEAD` 分支，因此它們從與遠端相符的乾淨樹開始。如果未配置遠端或提取失敗，worktree 會回退到您目前的本地 `HEAD`。要始終從本地 `HEAD` 分支，請在[設定](/zh-TW/settings#worktree-settings)中將 `worktree.baseRef` 設定為 `"head"`。將 `baseRef` 設定為 `"head"` 會使新 worktrees 帶有您未推送的提交和功能分支狀態，這在隔離需要在進行中的工作上操作的子代理時很有用。該設定僅接受 `"fresh"` 或 `"head"`，不接受任意 git refs：

```json theme={null}
{
  "worktree": {
    "baseRef": "head"
  }
}
```

要從特定的拉取請求分支，請傳遞以 `#` 為前綴的 PR 編號或完整的 GitHub 拉取請求 URL。Claude Code 從 `origin` 提取 `pull/<number>/head` 並在 `.claude/worktrees/pr-<number>` 建立 worktree：

```bash theme={null}
claude --worktree "#1234"
```

為了完全控制 worktrees 的建立方式，請配置 [`WorktreeCreate` hook](/zh-TW/hooks#worktreecreate)，它完全取代預設的 `git worktree` 邏輯。

<h2 id="copy-gitignored-files-into-worktrees">
  將 gitignored 檔案複製到 worktrees
</h2>

Worktree 是一個新的檢出，因此來自您主要儲存庫的未追蹤檔案（如 `.env` 或 `.env.local`）不存在。要在 Claude 建立 worktree 時自動複製它們，請將 `.worktreeinclude` 檔案新增到您的專案根目錄。

該檔案使用 `.gitignore` 語法。只有符合模式且也被 gitignored 的檔案才會被複製，因此追蹤的檔案永遠不會被重複。

此 `.worktreeinclude` 將兩個環境檔案和一個秘密配置複製到每個新 worktree：

```text .worktreeinclude theme={null}
.env
.env.local
config/secrets.json
```

這適用於使用 `--worktree` 建立的 worktrees、[子代理 worktrees](#isolate-subagents-with-worktrees) 和[桌面應用程式](/zh-TW/desktop#work-in-parallel-with-sessions)中的平行會話。

<h2 id="isolate-subagents-with-worktrees">
  使用 worktrees 隔離子代理
</h2>

子代理可以在自己的 worktrees 中執行，以便平行編輯不會衝突。要求 Claude「為您的代理使用 worktrees」，或通過將 `isolation: worktree` 新增到 frontmatter 在[自訂子代理](/zh-TW/sub-agents#supported-frontmatter-fields)上永久設定它。每個子代理都會獲得一個臨時 worktree，當子代理完成而沒有變更時會自動移除。

子代理 worktrees 使用與 `--worktree` 相同的[基礎分支](#choose-the-base-branch)，因此它們從您的儲存庫的預設分支分支，除非 `worktree.baseRef` 設定為 `"head"`。

<h2 id="clean-up-worktrees">
  清理 worktrees
</h2>

當您退出 worktree 會話時，清理取決於您是否進行了變更：

* **無未提交的變更、無未追蹤的檔案且無新提交**：worktree 及其分支會自動移除。如果會話有[名稱](/zh-TW/sessions#name-your-sessions)，Claude 會改為提示您，以便您可以稍後保留 worktree
* **存在未提交的變更、未追蹤的檔案或新提交**：Claude 會提示您保留或移除 worktree。保留會保留目錄和分支，以便您稍後可以返回。移除會刪除 worktree 目錄及其分支，丟棄所有未提交的變更、未追蹤的檔案和提交
* **非互動式執行**：使用 `--worktree` 與 `-p` 一起建立的 worktrees 不會自動清理，因為沒有退出提示。使用 `git worktree remove` 移除它們

Claude 為子代理和[背景會話](/zh-TW/agent-view#how-file-edits-are-isolated)建立的 Worktrees 一旦超過您的 [`cleanupPeriodDays`](/zh-TW/settings#available-settings) 設定，就會自動移除，前提是它們沒有未提交的變更、沒有未追蹤的檔案和沒有未推送的提交。您使用 `--worktree` 建立的 Worktrees 永遠不會被此掃描移除。

當代理正在執行時，Claude 會在其 worktree 上執行 `git worktree lock`，以便並行清理無法將其移除。當代理完成時，鎖定會被釋放。若要清理掃描保留的 worktree，請執行 `git worktree remove`，如果 worktree 有未提交的變更或未追蹤的檔案，請新增 `--force`。

<h2 id="manage-worktrees-manually">
  手動管理 worktrees
</h2>

為了完全控制 worktree 位置和分支配置，請直接使用 Git 建立 worktrees。當您需要檢出特定的現有分支或將 worktree 放在儲存庫外時，這很有用。

在新分支上建立 worktree：

```bash theme={null}
git worktree add ../project-feature-a -b feature-a
```

從現有分支建立 worktree：

```bash theme={null}
git worktree add ../project-bugfix bugfix-123
```

在 worktree 中啟動 Claude：

```bash theme={null}
cd ../project-feature-a && claude
```

列出您的 worktrees：

```bash theme={null}
git worktree list
```

完成後移除一個：

```bash theme={null}
git worktree remove ../project-feature-a
```

有關完整的命令參考，請參閱 [Git worktree 文件](https://git-scm.com/docs/git-worktree)。記住在每個新 worktree 中初始化您的開發環境：安裝依賴項、設定虛擬環境或執行您的專案設定所需的任何操作。

<h2 id="non-git-version-control">
  非 git 版本控制
</h2>

Worktree 隔離預設使用 git。對於 SVN、Perforce、Mercurial 或其他系統，請配置 [`WorktreeCreate` 和 `WorktreeRemove` hooks](/zh-TW/hooks#worktreecreate) 以提供自訂建立和清理邏輯。因為 hook 取代了預設的 git 行為，當您使用 `--worktree` 時，[`.worktreeinclude`](#copy-gitignored-files-into-worktrees) 不會被處理。改為在您的 hook 指令碼內複製任何本地配置檔案。

此 `WorktreeCreate` hook 從 stdin 讀取 worktree 名稱，檢出新的 SVN 工作副本，並列印目錄路徑，以便 Claude Code 可以將其用作會話的工作目錄：

```json theme={null}
{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}
```

將其與 `WorktreeRemove` hook 配對以在會話結束時進行清理。有關輸入架構和移除範例，請參閱 [hooks 參考](/zh-TW/hooks#worktreecreate)。

<h2 id="see-also">
  另請參閱
</h2>

Worktrees 處理檔案隔離。下面的相關頁面涵蓋將工作委派到這些隔離的檢出中以及在您建立的會話之間切換：

* [子代理](/zh-TW/sub-agents)：在會話內將工作委派給隔離的代理
* [代理團隊](/zh-TW/agent-teams)：自動協調多個 Claude 會話
* [管理會話](/zh-TW/sessions)：命名、恢復和在對話之間切換
* [桌面平行會話](/zh-TW/desktop#work-in-parallel-with-sessions)：桌面應用程式中由 worktree 支援的會話