Use Git worktrees
A standard Git repository typically uses a single worktree. To switch branches in this setup, you have to either commit or 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 locally without disrupting your existing environment, database state, or build artifacts.
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.
For more information about Git worktrees, refer to the official Git documentation.
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 .
In the Git tool window Alt+9, click
and select Worktrees.
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
.If the branch has an open pull request or merge request, its title is shown next to the branch name.
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 to prevent it from being moved, deleted, or pruned. Locked worktrees are marked with
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 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.
Create a Git worktree
Do one of the following:
In the Git tool window Alt+9, open the Worktrees tab and click
New Worktree.Click the VCS widget in the window header and select New Worktree.
In the main menu, select .
To create a worktree from a specific branch, in the VCS widget or in the Branches pane of the Log tab, select the branch and choose New Worktree from '<branch_name>'.
This opens the New Worktree dialog.
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.
Note that you cannot check out the same branch in two worktrees simultaneously. If you want to use the currently checked-out branch as a source for the new worktree, create another local branch from it: select the New branch checkbox and enter the name of the branch.
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, IntelliJ IDEA 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 (such as IDE project settings or .env files) that are not committed to Git.
Run setup script: run a script in the new worktree before IntelliJ IDEA opens it.
Click Create and Open Worktree.
IntelliJ IDEA 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.
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 or run a setup script when you create the worktree.
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.
In the New Worktree dialog, expand Copy local project setup.
Click Create to generate the
.worktreeincludefile with suggested patterns, or Edit to modify an existing one. IntelliJ IDEA opens the file in the editor.The suggested patterns cover common local configuration files and the IDE project settings.
Edit the file and click Continue in the editor banner to return to the dialog with your previous values.
If you close the file without clicking Continue, worktree creation is canceled.
Make sure the Copy files listed in .worktreeinclude checkbox is selected and click Create and Open Worktree.
After Git creates the worktree, IntelliJ IDEA 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, IntelliJ IDEA keeps the committed version.
Updates absolute paths in the copied
.ideaand.runfiles to point to the worktree.Removes
ProjectIdfrom the copied.idea/workspace.xmlfile.
Commit the .worktreeinclude file to your repository so that becomes available in all branches and can be reused for new worktrees.
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.
In the New Worktree dialog, expand Copy local project setup.
Select Run setup script and, in the Script field, specify the absolute path to the script.
IntelliJ IDEA 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, IntelliJ IDEA shows a notification and keeps the worktree.
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 IntelliJ IDEA, do the following:
In the Git tool window Alt+9, open the Worktrees tab.
Alternatively, in the main menu, select .
Double-click the target worktree or select it and press Enter.
Alternatively, right-click the worktree and select
Open Worktree.The worktree will open in a new or existing window depending on your system settings.
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.
For more information, refer to GitHub pull requests and GitLab merge requests.
If the branch of a worktree has an open pull request or merge request, you can open its review from the Worktrees tab:
In the Git tool window Alt+9, open the Worktrees tab.
Alternatively, in the main menu, select .
Right-click the worktree and select Open Review.
Lock and unlock worktrees
Lock a worktree to protect it from being moved, deleted, or pruned.
In the Git tool window Alt+9, open the Worktrees tab.
Alternatively, in the main menu, select .
Right-click the worktree and select Lock.
To unlock the worktree, right-click it and select Unlock.
Delete a worktree
Before deleting a worktree, make sure you have committed all changes.
In the Git tool window Alt+9, open the Worktrees tab.
Alternatively, in the main menu, select .
Select one or several worktrees and click
Delete.In a project with several Git repositories, you can delete several worktrees at once only if they belong to the same repository.
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.
In the Git tool window Alt+9, open the Worktrees tab.
Alternatively, in the main menu, select .
Click
Prune.
Troubleshooting
- IntelliJ IDEA treats separate worktrees as the same project
This could happen if the 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:
Close your project in IntelliJ IDEA.
Navigate to your Git worktree directory and delete the
workspace.xmlfile (alternatively, you can open the file and just delete theProjectIdline).Reopen the project in the IDE so it can generate a fresh, unique ID.
To prevent this from happening again, ensure is added to your repository's
.gitignorefile.If .idea/workspace.xml is not committed and you copy it to the new worktree by using
.worktreeinclude, IntelliJ IDEA removes theProjectIdfrom 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.