# 使用 Git 工作区树。

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/clion/llms.txt).

标准的 Git 仓库通常只使用一个工作区树。 在此设置中切换分支时，您必须要么 [提交](commit-and-push-changes.html#commit)，要么 [储藏](shelving-and-unshelving-changes.html#stash)未完成的修改。 Git 工作区树允许您在多个不同的目录中同时检出多个分支，所有这些目录都关联到同一个  `.git` 目录。

## 什么是 Git 工作区树？

Git 工作区树允许您在同一个仓库的多个分支下，同时在不同的目录中检出。 使用 Git 工作区树的常见用例如下：

* AI 驱动开发：在不同工作区树中运行 AI 代理，以防止其覆盖本地未保存的修改。

* 紧急错误修复：在单独的目录中解决关键问题，而不影响当前的工作进度。

* 并行代码审查：在本地检出并测试拉取请求和合并请求，而不会干扰您现有的环境、数据库状态或构建产物。

* 长时间运行的任务：在一个工作区树中执行大量测试套件或复杂的构建，同时可以在另一个工作区树中继续编写代码。

* 多分支上下文切换：管理多个长时间运行的分支，无需储藏修改或等待在分支切换后对大量文件进行索引重建。

Git 工作区树是您项目的一个关联副本。 与  `git clone` 不同，它会创建仓库的完整副本，而所有工作区树共享同一个中心  `.git` 历史。

当您创建一个工作区树时，Git 会为您的文件生成一个新目录。 与完整的  `.git` 文件夹不同，此目录包含一个  `.git` 文件，其纯文本路径指向原始仓库。 这样确保了所有工作区树都保持同步，同时又拥有独立的工作环境。

![主工作区树中的 Git 文件夹及已关联工作区树中的 Git 文件](https://resources.jetbrains.com/help/img/idea/2026.3/linked_worktree.png)

有关 Git 工作区树的更多信息，请参阅 [官方 Git 文档](https://git-scm.com/docs/git-worktree)。

## 创建和管理 Git 工作区树

> **Note:**
> CLion 目前仅支持包含单一仓库的项目使用 Git 工作区树。

如果项目已存在多个 Git 工作区树，则   工作树  选项卡默认可用。 否则，可以在   Git  工具窗口 `Alt+9` (Windows), `⌘ 9` (macOS), `⌘ 9` (IntelliJ IDEA Classic (macOS)), `⌘ 9` (macOS System Shortcuts), `Alt+9` (XWin), `Alt+9` (GNOME), `Alt+9` (KDE), `Alt+9` (Emacs), `Alt+9` (Sublime Text), `⌘ 9` (Sublime Text (macOS)), `⌘ 2` (Xcode), `Alt+9` (Visual Studio), `⌘ 9` (Visual Studio (macOS)), `Alt+9` (ReSharper), `⌘ 9` (ReSharper (macOS)), `Alt+9` (QtCreator), `⌘ 9` (QtCreator (macOS)), `Alt+9` (NetBeans), `Alt+9` (Eclipse), `⌘ 9` (Eclipse (macOS))中，通过点击 ![下移按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.chevronDownLarge.svg)并选择   工作树  打开。

![包含打开 Worktrees 选项卡选项的 Git 工具窗口](https://resources.jetbrains.com/help/img/idea/2026.3/open_worktrees_tab.png)

Procedure: 创建 Git 工作区树

1. 在   Git  工具窗口 `Alt+9` (Windows), `⌘ 9` (macOS), `⌘ 9` (IntelliJ IDEA Classic (macOS)), `⌘ 9` (macOS System Shortcuts), `Alt+9` (XWin), `Alt+9` (GNOME), `Alt+9` (KDE), `Alt+9` (Emacs), `Alt+9` (Sublime Text), `⌘ 9` (Sublime Text (macOS)), `⌘ 2` (Xcode), `Alt+9` (Visual Studio), `⌘ 9` (Visual Studio (macOS)), `Alt+9` (ReSharper), `⌘ 9` (ReSharper (macOS)), `Alt+9` (QtCreator), `⌘ 9` (QtCreator (macOS)), `Alt+9` (NetBeans), `Alt+9` (Eclipse), `⌘ 9` (Eclipse (macOS))中，打开   工作树  选项卡并点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)   新建工作树  。

或者，在主菜单中选择  `Git | 新建工作树` 。

这将打开   新建工作树  对话框。

![新建 Worktree 对话框](https://resources.jetbrains.com/help/img/idea/2026.3/new_worktree.png)

2. 在   新建工作树   对话框中，指定以下内容：

* 来自分支 ：选择源分支。 请注意，您不能同时在两个工作区树中检出同一个分支。 如果您想将当前检出的分支用作新工作区树的源，可以基于其创建另一个本地分支并在新工作区树中使用。 为此，请选择 新建分支 选项。 > **Note:** > 如果所选源分支为远程分支，则会创建同名本地分支，除非选择 新建分支 选项并提供一个不同于现有本地分支的新名称。

* 项目名称 ：新工作区树的名称。

* 位置 ：工作区树存储的目录。 避免嵌套工作区树：不建议在当前项目的目录下创建工作区树（例如， `Projects/mainProject/linkedWorktree` ）。 目前，CLion 会将此类项目误识别为多根项目，从而导致工作区树集成出错。

创建新工作区树后，CLion 会将其作为独立项目打开。

Procedure: 在不同工作区树间切换

首次打开工作区树后，它的表现与任何其他项目一样。 您可以在主菜单中的   最近的项目  ，或工具栏窗口标题的项目微件中找到它。

要切换到某个工作区树（包括在 CLion 之外创建的），请执行以下操作：

1. 在   Git  工具窗口 `Alt+9` (Windows), `⌘ 9` (macOS), `⌘ 9` (IntelliJ IDEA Classic (macOS)), `⌘ 9` (macOS System Shortcuts), `Alt+9` (XWin), `Alt+9` (GNOME), `Alt+9` (KDE), `Alt+9` (Emacs), `Alt+9` (Sublime Text), `⌘ 9` (Sublime Text (macOS)), `⌘ 2` (Xcode), `Alt+9` (Visual Studio), `⌘ 9` (Visual Studio (macOS)), `Alt+9` (ReSharper), `⌘ 9` (ReSharper (macOS)), `Alt+9` (QtCreator), `⌘ 9` (QtCreator (macOS)), `Alt+9` (NetBeans), `Alt+9` (Eclipse), `⌘ 9` (Eclipse (macOS))中，打开   工作树  选项卡。

或者，在主菜单中选择  `Git | 工作树` 。

2. 双击目标工作区树。

![Git 工具窗口中的 Worktrees 选项卡，包含多个工作区树](https://resources.jetbrains.com/help/img/idea/2026.3/several_worktrees.png)

根据您的系统设置，工作区树将在新窗口或现有窗口中打开。

默认情况下，   工作树   选项卡不会显示任何活动工作树的状态。 只有当工作树输入特定状态时，状态指示器才会显示在列表中：

* 已锁定 ：工作树已被外部锁定，以防止其被移动、 [删除](#delete-a-worktree)或 [修剪](#prune-worktrees)。

* 可修剪 ：工作树目录已被手动从文件系统中移除。 这些记录可以安全地 [修剪](#prune-worktrees)，以清理您的仓库。

> **Tip:**
> 您还可以通过 VCS 微件，或   日志  选项卡的   Git  工具窗口，选择当前在工作区树中检出的分支，右键点击并选择   打开工作树  来打开工作区树。

Procedure: 删除工作区树

删除工作区树前，请确保您已提交所有修改。

1. 在   Git  工具窗口 `Alt+9` (Windows), `⌘ 9` (macOS), `⌘ 9` (IntelliJ IDEA Classic (macOS)), `⌘ 9` (macOS System Shortcuts), `Alt+9` (XWin), `Alt+9` (GNOME), `Alt+9` (KDE), `Alt+9` (Emacs), `Alt+9` (Sublime Text), `⌘ 9` (Sublime Text (macOS)), `⌘ 2` (Xcode), `Alt+9` (Visual Studio), `⌘ 9` (Visual Studio (macOS)), `Alt+9` (ReSharper), `⌘ 9` (ReSharper (macOS)), `Alt+9` (QtCreator), `⌘ 9` (QtCreator (macOS)), `Alt+9` (NetBeans), `Alt+9` (Eclipse), `⌘ 9` (Eclipse (macOS))中，打开   工作树  选项卡。

或者，在主菜单中选择  `Git | 工作树` 。

2. 选择工作区树并点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.delete.svg)   删除  。

> **Note:**
> 无法删除主工作树或当前打开的工作树。

Procedure: 修剪工作树

如果您手动删除了工作树目录，而不是在 IDE 中 [删除工作树](#delete-a-worktree)，Git 会检测到文件缺失，并将该工作树标记为   可修剪  。 修剪操作会移除丢失工作树的 Git 内部记录，并释放其关联分支。

1. 在   Git  工具窗口 `Alt+9` (Windows), `⌘ 9` (macOS), `⌘ 9` (IntelliJ IDEA Classic (macOS)), `⌘ 9` (macOS System Shortcuts), `Alt+9` (XWin), `Alt+9` (GNOME), `Alt+9` (KDE), `Alt+9` (Emacs), `Alt+9` (Sublime Text), `⌘ 9` (Sublime Text (macOS)), `⌘ 2` (Xcode), `Alt+9` (Visual Studio), `⌘ 9` (Visual Studio (macOS)), `Alt+9` (ReSharper), `⌘ 9` (ReSharper (macOS)), `Alt+9` (QtCreator), `⌘ 9` (QtCreator (macOS)), `Alt+9` (NetBeans), `Alt+9` (Eclipse), `⌘ 9` (Eclipse (macOS))中，打开   工作树  选项卡。

或者，在主菜单中选择  `Git | 工作树` 。

2. 点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app-client.expui.actions.clearCash.svg)   修剪  。

> **Note:**
> 此操作会一次性清除所有可修剪的工作树，无论您当前选择了哪些。

## 故障排查

CLion 将单独的工作树视为同一个项目
: 如果  `.idea/workspace.xml`  文件被提交到仓库，可能会发生这种情况。 由于此文件包含唯一的  `ProjectId` ，创建新的 Git 工作树时会重复该 ID。 因此，IDE 会因相同的 ID 而混淆，并错误地将两个目录视为同一个项目。
:
:
:
: 如何修复：
:
:
:
: 1.  在 CLion 中关闭您的项目。
:
: 2.  导航到您的 Git 工作树目录并删除  `workspace.xml`  文件（或者，您可以打开文件，只删除  `ProjectId`  行）。
:
: 3.  在 IDE 中重新打开项目，以便生成新的唯一 ID。
:
:
:
: 为防止此问题再次发生，请确保将  `.idea/workspace.xml`  添加到您的仓库  `.gitignore`  文件中。

