Git Worktree: How to Work on Two Features without Constantly Checking Out

When working on a project with Git, there are situations that almost always disrupt the flow: You are developing a new feature, and suddenly you need to fix a bug in another branch. The common way is to run git stash, switch branches, complete the hotfix, and then restore the previous changes. The problem is, stashes can pile up and sometimes make us forget which changes need to be restored.

Git has a more convenient feature for such cases: git worktree. This feature allows a single repository to have multiple working folders at the same time. Each folder can use a different branch while still sharing the same repository objects. Simply put, you can have an payment-feature folder and a login-hotfix folder active simultaneously without constantly checking out.

What is Git worktree?

In regular Git usage, a single repository typically has one working folder. When you run git switch or git checkout, the contents of that folder change according to the selected branch.

With worktree, a single repository can have one main folder and several additional folders linked to that repository. Each worktree has its own HEAD and index, so changes in one folder do not automatically disrupt work in another folder. The heavy Git data remains shared, so you don't need to perform a full clone repeatedly.

This feature is different from manually copying project folders. A regular copy does not have the correct administrative relationship with the main repository and can cause confusion when used for commits or branch switching.

Creating the first worktree

For example, you are in the online-store repository and want to create a folder specifically for hotfixes.

git worktree add ../online-store-hotfix hotfix/login

This command creates the folder ../online-store-hotfix and opens the hotfix/login branch within it. If that branch is already available locally, Git will use it. You can enter that folder and work as usual:

cd ../online-store-hotfix
git status
# make changes
git add .
git commit -m "Fix login validation"

Meanwhile, the main repository folder remains on the previous branch. You can return to working on the feature without having to stash.

Creating a new branch at the same time

If the branch for the new work does not exist yet, use the -b option:

git worktree add -b payment-feature ../online-store-payment main

This command creates a new branch named payment-feature based on main, and places it in the ../online-store-payment folder.

The folder name is free, but it should be made easily recognizable. A simple naming pattern could be:

• ../project-main for main work.
• ../project-hotfix for urgent fixes.
• ../project-review for checking pull requests.

Viewing and deleting worktrees

To see all worktrees connected to the repository, run:

git worktree list

Git will display the folder locations, the commits currently in use, and the active branches. This is useful when you already have several folders and start forgetting which ones are used for specific tasks.

Once the work is done and the folder is no longer needed, delete the worktree with:

git worktree remove ../online-store-hotfix

This command removes the worktree folder and the associated metadata. The branches you have committed are not automatically deleted. If the folder was ever deleted manually through a file manager, old metadata may linger. In such situations, use:

git worktree prune

The prune command cleans up records of worktrees that no longer have target folders.

Important rules that often surprise

Generally, a single branch should not be active in two worktrees at the same time. This is a safeguard to prevent two folders from writing changes to the same branch simultaneously, resulting in a difficult-to-track state.

For example, if the main branch is active in the main folder, Git will usually reject attempts to open the main branch again in another worktree. The solution is not to force it, but to use a different branch according to the work's purpose.

Since worktrees share most of the repository data, do not think of them as two completely isolated projects. Certain configurations can still be shared, especially if you change Git settings at the repository level. For needs that must differ per folder, Git provides specific worktree configurations through the extensions.worktreeConfig setting.

Be mindful of local dependencies and services

Worktree separates source files, but does not automatically separate everything outside of Git. If the project uses local dependencies, databases, containers, or configuration files pointing to specific ports, two worktrees may collide.

For example, two Node.js folders might both use a .env file with the same database port. Two application processes then compete for the port or write to the same database. To avoid this, use separate test databases, different ports, or local configuration files specifically prepared for each worktree.

The same applies to build output folders, caches, and files not tracked by Git. Ensure that the build process does not write to a shared location that should only be used by one job.

When is worktree most useful?

• Sudden hotfixes: the feature work remains open while bug fixes are worked on in another folder.
• Code reviews: you can check out a colleague's branch without disrupting local changes.
• Version comparisons: two branches can be run or tested side by side.
• Projects with legacy builds: you do not have to wait for the checkout and reinstallation process every time you switch contexts.
• Temporary experiments: create a separate worktree, then delete it after the results are no longer needed.

What you can do now

If you often use git stash just because you need to switch tasks, try this simple workflow:

1. Ensure that the changes you are working on have a clear commit, or at least are safely stored.
2. Create a new worktree for the hotfix or review branch.
3. Use different folders for each work context.
4. Regularly check the list of worktrees with git worktree list.
5. Remove completed worktrees with git worktree remove.

Git worktree is not a replacement for branches, stashes, or clones in all situations. However, for developers who frequently switch contexts, this feature reduces unnecessary administrative work. You can leave one folder in a ready state while using another folder to address more urgent needs.

The official Git documentation explains that additional worktrees share most of the repository data but have per-worktree metadata such as HEAD and their own index. Complete details about the add, list, remove, lock, and prune commands are available in the git-worktree documentation.

Sources & further reading

• Git - git-worktree Documentation

– Rio Yotto @rioyotto