# Use Git worktrees

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

A standard Git repository typically uses a single worktree. To switch branches in this setup, you have to either [commit](commit-and-push-changes.html#commit) or [stash](shelving-and-unshelving-changes.html#stash) unfinished work. Git worktrees allow you to have multiple branches checked out simultaneously in separate directories, all linked to a single `.git` directory.

## What is a Git worktree?

A Git worktree allows you to have multiple branches of the same repository checked out simultaneously in separate directories.  Common use cases for using Git worktrees include:

* AI-driven development: run AI agents in separate worktrees to prevent them from overwriting local unsaved changes.

* Emergency bug fixes: address critical issues in a separate directory without interrupting your current progress.

* Parallel code reviews: [check out and test pull and merge requests](#review-in-worktree) locally without disrupting your current state.

* Long-running tasks: execute heavy test suites or complex builds in one worktree while continuing to write code in another.

* Multi-branch context switching: manage several long-running branches without stashing changes or waiting for the reindexing of a large volume of files after a branch switch.

A Git worktree is a linked copy of your project.  Unlike `git clone`, which creates a full duplicate of the repository, all worktrees share the same central `.git` history.

When you create a worktree, Git generates a new directory for your files. Instead of a full `.git` folder, this directory contains a `.git` file with a plain-text path pointing back to the original repository. This ensures all worktrees remain in sync while maintaining independent working environments.

![The Git folder in the main worktree and a Git file in the linked worktree](https://resources.jetbrains.com.cn/help/img/idea/2026.3/linked_worktree.png)

For more information about Git worktrees, refer to [the official Git documentation](https://git-scm.com/docs/git-worktree).

## Create and manage Git worktrees

If at least one repository in your project has more than one Git worktree, the Worktrees tab is available by default. Otherwise, open it in one of the following ways:

* In the main menu, select `Git | Worktrees`.

* In the Git tool window `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)), `Ctrl+Shift+G` (VSCode), `⌃ ⇧ G` (VSCode (macOS)) , click ![the Down button](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.chevronDownLarge.svg) and select Worktrees.

![The Git tool window with an option to open the Worktrees tab](https://resources.jetbrains.com.cn/help/img/idea/2026.3/open_worktrees_tab.png)

If your project contains several Git repositories, each worktree belongs to one of them. The Worktrees tab lists the worktrees of all repositories, and a colored stripe next to each worktree indicates the repository that it belongs to.

### Worktrees tab

Each row in the Worktrees tab shows the name of the worktree directory and the branch that is checked out in it:

* The main worktree is shown in bold.

* The worktree that is open in the current window is marked with ![the Checked icon](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.actions.checked.svg).

* If the branch has an open pull request or merge request, its title is shown next to the branch name.

![Worktrees tab in the Git tool window with several worktrees](https://resources.jetbrains.com.cn/help/img/idea/2026.3/several_worktrees.png)

To view the location of a worktree, hover over it. The tooltip also shows whether the worktree is main or linked and whether it is in one of the following states:

* Locked: the worktree was [locked](#lock-a-worktree) to prevent it from being moved, [deleted](#delete-a-worktree), or [pruned](#prune-worktrees). Locked worktrees are marked with ![the Locked icon](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.locked.svg) in the list.

* Prunable: the worktree directory was removed manually from the file system. Prunable worktrees are dimmed in the list. These records can be safely [pruned](#prune-worktrees) to clean up your repository.

To find a worktree, start typing its name or the name of its branch while the list is in focus.

Procedure: Create a Git worktree

1. In the   Git tool window  `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)), `Ctrl+Shift+G` (VSCode), `⌃ ⇧ G` (VSCode (macOS)) , open the Worktrees tab and click ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.add.svg) New Worktree.

Alternatively, use one of the following options:

* Click the VCS widget in the window header and select New Worktree.

* In the main menu, select `Git | New Worktree`.

* To create a worktree from a specific branch, in the VCS widget or in the [Branches pane](log-tab.html#BranchesPane) of the Log tab, right-click the branch and choose New Worktree from '<branch_name>'.

* To create a worktree for a recent project without opening the project, on the GoLand Home screen, hover over the project, click ![Version Control](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.vcs.vcs.svg) Version Control, and select New Worktree. For more information, refer to [Manage Git branches](manage-branches.html#branches-popup-home-screen).

This opens the New Worktree dialog.

![New Worktree dialog](https://resources.jetbrains.com.cn/help/img/idea/2026.3/new_worktree.png)

2. In the New Worktree dialog, specify the following:

* Repository: the repository for which you want to create the worktree. This field is available only if your project contains several Git repositories.

* From branch: select the local branch, remote branch, or tag to check out in the new worktree. If the selected source branch is remote, then a local branch with the same name will be created unless you select the New branch checkbox and provide a new name that does not coincide with existing local branches. If the branch is already checked out in another worktree, you can still use it: when GoLand asks you to confirm, click Create Anyway. Both worktrees then [share the branch](#same-branch-in-several-worktrees). To work in them independently, select the New branch checkbox instead.

* Project name: the name of the new worktree. By default, the name consists of the repository directory name and the branch name.

* Location: the parent directory in which the worktree directory will be created. The full path to the new worktree is shown below the field. By default, GoLand suggests the location that you used last time, or a directory outside your current project. Avoid nesting worktrees: it is not recommended to create a worktree inside the directory of your current project (for example, `Projects/mainProject/linkedWorktree`).

* Copy local project setup: expand this section to set up the new worktree the same way as your current project: * Copy files listed in .worktreeinclude: [copy local files](#copy-local-files) (such as IDE project settings or `.env` files) that are not committed to Git. * Run setup script: [run a script](#run-setup-script) in the new worktree before GoLand opens it.

3. Click Create and Open Worktree.

If you started from the GoLand Home screen, click Create Worktree instead.

GoLand creates the worktree and opens it as a separate project. In a project with several Git repositories, the new project contains only the worktree of the selected repository.

If you create a worktree from the GoLand Home screen, GoLand does not open it. Instead, a notification shows the location of the new worktree.

> **Note:**
> If the selected repository is a Git submodule, the new worktree does not replace the submodule in the parent repository.

### Copy the local project setup to a new worktree

When you create a worktree, Git checks out only the files that are committed to the repository. Local files, such as IDE project settings, run configurations, or `.env` files, stay in your current project. To use them in the new worktree, you can [copy them](#copy-local-files) or [run a setup script](#run-setup-script) when you create the worktree.

If you have feedback about copying the local project setup, share it in a [YouTrack issue](https://youtrack.jetbrains.com/newIssue?project=IJPL&summary=%5Bworktree%5D&description=**IDE+version%2C+OS**%3A%0A%0A%23%23%23+Steps+to+reproduce%0A%0A1.+%0A%0A%23%23%23+Actual+result%0A%0A%0A%0A%23%23%23+Expected+result%0A%0A%0A&c=Subsystem+Version+Control.+Git&c=Assignee+VCS_Developer).

Procedure: Copy local files to a new worktree

To specify which local files to copy, list their patterns in the `.worktreeinclude` file in the repository root. The file uses the `.gitignore` syntax, one pattern per line, and can be generated during the creation of a new worktree.

1. In the [New Worktree](#create-a-git-worktree) dialog, expand Copy local project setup.

2. Click Create to generate the `.worktreeinclude` file with suggested patterns, or Edit to modify an existing one. GoLand opens the file in the editor.

The suggested patterns cover common local configuration files and the IDE project settings.

> **Note:**
> The suggested patterns do not include:
>
>
>
> * IDE project settings, if `.idea/workspace.xml` is committed, which is [not recommended](#ide-treats-separate-worktrees-as-the-same-project).
>
> * Module files. If your `.iml` files are not committed, add a pattern for them, for example, `*.iml`.

3. Edit the file and click Continue in the editor banner to return to the dialog with your previous values.

![.worktreeinclude file open in the editor with suggested file patterns and a banner with Continue to return to the New Worktree dialog](https://resources.jetbrains.com.cn/help/img/idea/2026.3/worktreeinclude.png)

If you close the file without clicking Continue, worktree creation is canceled.

4. Make sure the Copy files listed in .worktreeinclude checkbox is selected and click Create and Open Worktree.

![Copy local project setup section of the New Worktree dialog with Copy files listed in .worktreeinclude selected and Run setup script cleared](https://resources.jetbrains.com.cn/help/img/idea/2026.3/copy_files_checkbox.png)

After Git creates the worktree, GoLand does the following:

* Copies the files that match the patterns and are not committed in your current worktree: untracked, ignored, or staged files. If the checked-out branch already contains a file, GoLand keeps the committed version.

* Updates absolute paths in the copied `.idea` and `.run` files to point to the worktree.

* Removes `ProjectId` from the copied `.idea/workspace.xml` file.

Commit the `.worktreeinclude` file to your repository so that becomes available in all branches and can be reused for new worktrees.

Procedure: Run a setup script for a new worktree

To install dependencies, generate files, or run other setup tasks, run a script when you create the worktree.

1. In the New Worktree dialog, expand Copy local project setup.

2. Select Run setup script and, in the Script field, specify the absolute path to the script.

GoLand runs the script in the worktree directory, with the worktree path as an argument, before it opens the project. If the script fails or runs longer than 5 minutes, GoLand shows a notification and keeps the worktree.

> **Note:**
> GoLand does not copy local files or run the setup script when you [open a pull or merge request in a worktree](#review-in-worktree).

Procedure: Switch between different worktrees

Once a worktree has been opened for the first time, it behaves like any other project. You can find it in Recent Projects in the main menu or in the project widget in the toolbar in the window header.

To switch to a worktree, including the ones created outside of GoLand, do the following:

1. In the   Git tool window  `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)), `Ctrl+Shift+G` (VSCode), `⌃ ⇧ G` (VSCode (macOS)) , open the Worktrees tab.

Alternatively, in the main menu, select `Git | Worktrees`.

2. Double-click the target worktree or select it and press `Enter`.

Alternatively, right-click the worktree and select ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.open.svg) Open Worktree.

The worktree will open in a new or existing window depending on your system settings.

You can also switch to a worktree by using the branch that is checked out in it: in the VCS widget or in the Log tab of the Git tool window, right-click the branch and select Open Worktree. If the branch is checked out in several worktrees, select the one to open in the Choose Worktree to Open dialog.

If you select Checkout for such a branch instead, the Worktree Conflict dialog opens. In this dialog, click Open Existing Worktree to switch to the worktree, or Checkout Anyway to check out the branch in the current project as well, so that both worktrees use the same branch.

> **Warning:**
> If a branch is checked out in several worktrees, commit to it from only one of them. Otherwise, a commit from another worktree can undo your changes.
>
>
>
> When you commit changes in one worktree, the same files appear as modified in the other worktrees with this branch. These files still contain their previous versions, so committing them from another worktree restores the previous versions on the branch.
>
>
>
> Before you continue working on the branch in another worktree, [roll back](undo-changes.html#revert-local-changes) these files there.

Procedure: Review a pull or merge request in a worktree

You can open the branch of a pull request or a merge request in a separate worktree to review and test the changes without switching branches in your current project. For that, select Open in Worktree for the pull request or merge request.

![Pull Requests tool window with a pull request context menu open and Open in Worktree selected to review its branch in a separate worktree](https://resources.jetbrains.com.cn/help/img/idea/2026.3/pr_branch_open_in_worktree.png)

For more information, refer to [GitHub pull requests](work-with-github-pull-requests.html#open-pull-request-in-worktree)  and [GitLab merge requests](work-with-gitlab-merge-requests.html#open-merge-request-in-worktree) .

If the branch of a worktree has an open pull request or merge request, you can open its review from the Worktrees tab:

1. In the   Git tool window  `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)), `Ctrl+Shift+G` (VSCode), `⌃ ⇧ G` (VSCode (macOS)) , open the Worktrees tab.

Alternatively, in the main menu, select `Git | Worktrees`.

2. Right-click the worktree and select Open Review.

![Worktrees tab with the context menu of a worktree whose branch has an open pull request, and the Open Review option selected](https://resources.jetbrains.com.cn/help/img/idea/2026.3/worktree_open_review.png)

Procedure: Lock and unlock worktrees

Lock a worktree to protect it from being moved, [deleted](#delete-a-worktree), or [pruned](#prune-worktrees).

1. In the   Git tool window  `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)), `Ctrl+Shift+G` (VSCode), `⌃ ⇧ G` (VSCode (macOS)) , open the Worktrees tab.

Alternatively, in the main menu, select `Git | Worktrees`.

2. Right-click the worktree and select Lock.

To unlock the worktree, right-click it and select Unlock.

> **Note:**
> You cannot lock the main worktree or the worktree that is currently open.

Procedure: Delete a worktree

Before deleting a worktree, make sure you have committed all changes.

1. In the   Git tool window  `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)), `Ctrl+Shift+G` (VSCode), `⌃ ⇧ G` (VSCode (macOS)) , open the Worktrees tab.

Alternatively, in the main menu, select `Git | Worktrees`.

2. Select one or several worktrees and click ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.delete.svg) Delete.

In a project with several Git repositories, you can delete several worktrees at once only if they belong to the same repository.

> **Note:**
> You cannot delete the main worktree or the worktree that is currently open.

Procedure: Prune worktrees

If you delete a worktree directory manually rather than using Git, Git will detect that the files are missing and mark the worktree as Prunable. Pruning removes the internal Git records for the missing worktrees and frees up their associated branches.

1. In the   Git tool window  `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)), `Ctrl+Shift+G` (VSCode), `⌃ ⇧ G` (VSCode (macOS)) , open the Worktrees tab.

Alternatively, in the main menu, select `Git | Worktrees`.

2. Click ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.actions.clearCash.svg) Prune.

> **Note:**
> This action clears all prunable worktrees of the repository at once, regardless of your current selection. In a project with several Git repositories, GoLand prunes the worktrees of the repository that the selected worktree belongs to.

## Troubleshooting

GoLand treats separate worktrees as the same project
: This could happen if the `.idea/workspace.xml` file was committed to your repository. As this file contains a unique `ProjectId`, creating a new Git worktree duplicates that ID. As a result, the IDE becomes confused by the identical IDs and incorrectly treats both directories as a single project.
:
:
:
: How to fix it:
:
:
:
: 1.  Close your project in GoLand.
:
: 2.  Navigate to your Git worktree directory and delete the `workspace.xml` file (alternatively, you can open the file and just delete the `ProjectId` line).
:
: 3.  Reopen the project in the IDE so it can generate a fresh, unique ID.
:
:
:
: To prevent this from happening again, ensure `.idea/workspace.xml` is added to your repository's `.gitignore` file.
:
:
:
: If `.idea/workspace.xml` is not committed and you [copy it to the new worktree](#copy-local-files) by using `.worktreeinclude`, GoLand removes the `ProjectId` from the copy automatically.

The Open in Worktree action is not available for a pull or merge request
: Opening pull requests and merge requests in a worktree is available only for projects that contain a single Git repository. The action is also not available if the branch of the pull request or merge request is already checked out in the current project.

