PyCharm 2026.2 Help

使用 Git 工作区树。

标准 Git 仓库通常只使用一个工作区树。 在此设置下切换分支时,您必须先 提交保存暂存未完成的工作。 Git 工作区树允许您在不同的目录下同时检出多个分支,这些目录都连接到同一个 .git 目录。

什么是 Git 工作区树?

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

  • AI 驱动开发:在单独的工作区树中运行 AI 代理,避免其覆盖本地未保存的更改。

  • 紧急错误修复:在单独的目录中处理严重问题,不影响当前进展。

  • 并行代码审查:在本地检出和测试拉取和合并请求,不干扰现有环境、数据库状态或构建产物。

  • 长时间运行的任务:在一个工作区树中执行大型测试套件或复杂构建,同时在另一个中继续编写代码。

  • 多分支上下文切换:管理多个长时间运行的分支,无需暂存更改或在切换分支后等待大量文件重新索引。

Git 工作区树是您项目的链接副本。 与 git clone (会完整复制仓库)不同,所有工作区树共享同一个中心 .git 历史记录。

创建工作区树时,Git 会为您的文件生成一个新目录。 此目录不再是完整的 .git 文件夹,而是包含一个 .git 文件,该文件以纯文本路径指向原始仓库。 这样可确保所有工作区树保持同步,同时维持独立的工作环境。

主工作区树中的 Git 文件夹及链接工作区树中的 Git 文件

有关 Git 工作区树的更多信息,请参阅 官方 Git 文档

创建和管理 Git 工作区树

如果项目已存在多个 Git 工作区树,则 工作区树形结构 (Worktrees) 选项卡默认可用。 否则,可以在 Git 工具窗口 Alt+9 里,通过点击 向下按钮 并选择 工作区树形结构 (Worktrees) 来打开。

Git 工具窗口,可打开工作区树选项卡

创建 Git 工作区树

  1. Git 工具窗口 Alt+9 中,打开 工作区树形结构 (Worktrees) 选项卡并点击 新建工作区树形结构 (New Worktree)

    或者,从主菜单中选择 Git | 新建工作区树形结构 (New Worktree)

    这将打开 新建工作区树形结构 (New Worktree) 对话框。

    新建工作区树对话框
  2. 新建工作区树形结构 (New Worktree) 对话框中,指定以下内容:

    • 基于分支 :选择源分支。

      注意,不能同时在两个工作区树中检出同一分支。 如果您想将当前检出的分支作为新工作区树的源,可以基于此分支创建另一个本地分支并用于新工作区树。 为此,选择 新建分支 选项。

    • 项目名称 :新工作区树名称。

    • 位置 :存储该工作区树的目录。

      避免嵌套工作区树:不建议在当前项目的目录内创建工作区树(例如, Projects/mainProject/linkedWorktree)。 目前,PyCharm 会错误识别这些项目为多根项目,从而导致工作区树集成失效。

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

在不同工作区树之间切换

首次打开工作区树后,其表现与其他项目相同。 您可以在主菜单的 最近项目 或窗口头部工具栏的项目微件中找到它。

要切换到某个工作区树(包括在 PyCharm 外部创建的工作区树),请执行以下操作:

  1. Git 工具窗口 Alt+9 中,打开 工作区树形结构 (Worktrees) 选项卡。

    或者,从主菜单中选择 Git | 工作区树形结构 (Worktrees)

  2. 双击目标工作区树。

    Git 工具窗口的工作区树选项卡,包含多个工作区树

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

默认情况下, 工作区树形结构 (Worktrees) 选项卡不会显示任何活动工作树的状态。 只有当工作树进入特定状态时,状态指示器才会出现在列表中:

  • 已锁定 :该工作树被外部锁定,以防止其被移动、 删除修剪

  • 可修剪 :工作树目录已被手动从文件系统中移除。 这些记录可以安全地 修剪 ,以清理您的仓库。

删除工作区树

删除工作区树前,请确保您已经提交了所有更改。

  1. Git 工具窗口 Alt+9 中,打开 工作区树形结构 (Worktrees) 选项卡。

    或者,从主菜单中选择 Git | 工作区树形结构 (Worktrees)

  2. 选择要删除的工作区树并点击 删除

修剪工作树

如果您手动删除了工作树目录,而不是在 IDE 中 删除工作树 ,Git 会检测到文件丢失并将工作树标记为 可修剪。 修剪会移除 Git 对缺失工作树的内部记录,并释放其关联的分支。

  1. Git 工具窗口 Alt+9 中,打开 工作区树形结构 (Worktrees) 选项卡。

    或者,从主菜单中选择 Git | 工作区树形结构 (Worktrees)

  2. 点击 修剪

故障排除

PyCharm 将单独的工作树视为同一个项目

如果 .idea/workspace.xml 文件被提交到您的仓库,就可能发生此情况。 由于该文件包含唯一的 ProjectId ,创建新的 Git 工作树会复制该 ID。 因此,IDE 会因 ID 相同而无法区分,错误地将这两个目录视为同一项目。

如何修复:

  1. 请在 PyCharm 中关闭您的项目。

  2. 转到您的 Git 工作树目录并删除 workspace.xml 文件(或者,您可以打开该文件并仅删除 ProjectId 行)。

  3. 重新在 IDE 中打开项目,以便生成一个全新的唯一 ID。

为防止此问题再次发生,请确保将 .idea/workspace.xml 添加到您的仓库 .gitignore 文件中。

2026年 7月 14日