# Use Git worktrees 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 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. ![The Git folder in the main worktree and a Git file in the linked worktree](https://resources.jetbrains.com.cn/help/img/idea/2026.2/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 > **Note:** > IntelliJ IDEA currently supports Git worktrees for projects containing a single repository. If a project already has more than one Git worktree, the Worktrees tab is available by default. Otherwise, it can be opened 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)), `Alt+9` (NetBeans), `Alt+9` (Visual Studio), `⌘ 9` (Visual Studio (macOS)), `Alt+9` (Eclipse), `⌘ 9` (Eclipse (macOS)) by clicking ![the Down button](https://resources.jetbrains.com.cn/help/img/idea/2026.2/app.expui.general.chevronDownLarge.svg) and selecting Worktrees. ![The Git tool window with an option to open the Worktrees tab](https://resources.jetbrains.com.cn/help/img/idea/2026.2/open_worktrees_tab.png) 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)), `Alt+9` (NetBeans), `Alt+9` (Visual Studio), `⌘ 9` (Visual Studio (macOS)), `Alt+9` (Eclipse), `⌘ 9` (Eclipse (macOS)) , open the Worktrees tab and click ![](https://resources.jetbrains.com.cn/help/img/idea/2026.2/app.expui.general.add.svg) New Worktree. Alternatively, in the main menu, select `Git | New Worktree`. This opens the New Worktree dialog. ![New Worktree dialog](https://resources.jetbrains.com.cn/help/img/idea/2026.2/new_worktree.png) 2. In the New Worktree dialog, specify the following: * From branch: select the source branch. 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, you can create another local branch from it and use it in the new worktree. For that, select the New Branch option. > **Note:** > If the selected source branch is remote, then a local branch with the same name will be created unless you select the New branch option and provide a new name that does not coincide with existing local branches. * Project name: the name of the new worktree. * Location: the directory where the worktree will be stored. Avoid nesting worktrees: it is not recommended to create a worktree inside the directory of your current project (for example, `Projects/mainProject/linkedWorktree`). Currently, IntelliJ IDEA misidentifies such projects as multi-root projects, which breaks the worktree integration. Once you create a new worktree, IntelliJ IDEA will open it as a separate project. 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 IntelliJ IDEA, 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)), `Alt+9` (NetBeans), `Alt+9` (Visual Studio), `⌘ 9` (Visual Studio (macOS)), `Alt+9` (Eclipse), `⌘ 9` (Eclipse (macOS)) , open the Worktrees tab. Alternatively, in the main menu, select `Git | Worktrees`. 2. Double-click the target worktree. ![Worktrees tab in the Git tool window with several worktrees](https://resources.jetbrains.com.cn/help/img/idea/2026.2/several_worktrees.png) The worktree will open in a new or existing window depending on your system settings. By default, the Worktrees tab does not display any statuses for active worktrees. A status indicator only appears in the list if the worktree enters a specific state: * Locked: the worktree was locked externally to prevent it from being moved, [deleted](#delete-a-worktree), or [pruned](#prune-worktrees). * Prunable: the worktree directory was removed manually from the file system. These records can be safely [pruned](#prune-worktrees) to clean up your repository. > **Tip:** > You can also open worktrees via the VCS widget or the Log tab of the Git tool window by selecting a branch that is currently checked out in a worktree, right-clicking it and selecting Open Worktree. 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)), `Alt+9` (NetBeans), `Alt+9` (Visual Studio), `⌘ 9` (Visual Studio (macOS)), `Alt+9` (Eclipse), `⌘ 9` (Eclipse (macOS)) , open the Worktrees tab. Alternatively, in the main menu, select `Git | Worktrees`. 2. Select the worktree and click ![](https://resources.jetbrains.com.cn/help/img/idea/2026.2/app.expui.general.delete.svg) Delete. > **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 [deleting a worktree](#delete-a-worktree) in the IDE, 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)), `Alt+9` (NetBeans), `Alt+9` (Visual Studio), `⌘ 9` (Visual Studio (macOS)), `Alt+9` (Eclipse), `⌘ 9` (Eclipse (macOS)) , open the Worktrees tab. Alternatively, in the main menu, select `Git | Worktrees`. 2. Click ![](https://resources.jetbrains.com.cn/help/img/idea/2026.2/app-client.expui.actions.clearCash.svg) Prune. > **Note:** > This action clears all prunable worktrees at once, regardless of your current selection. ## Troubleshooting IntelliJ IDEA 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 IntelliJ IDEA. : : 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.