Git Worktree: How to Handle Two Branches Without C…

Switching branches with git switch is usually sufficient. Problems arise when ongoing work isn't finished, but suddenly there's a bug that needs immediate fixing. Stashing changes, switching branches, and then restoring them can be done, but the workflow quickly becomes cumbersome.

This is where Git worktree comes in handy. This built-in Git feature allows a single repository to have multiple working trees—work folders that can each be on different branches. This way, a feature branch can remain open in one folder while a hotfix is worked on in another. ([git-scm.com](https://git-scm.com/docs/git-worktree?utm_source=openai))

What is Git worktree?

Imagine a repository as the main project, and then you create several work tables for the same project. Each table has its own folder and branch, but important repository metadata is still managed together.

The main repository is usually referred to as the main worktree. Additional folders created with the git worktree add command are called linked worktrees. Each worktree has its own HEAD position and index, so changes in one folder do not have to disrupt the others. ([git-scm.com](https://git-scm.com/docs/git-worktree?utm_source=openai))

This is different from simply copying the repository folder manually. A regular copy can have separate Git metadata and risks causing confusion. A worktree is officially linked to the original repository and can be managed with Git commands.

When is this feature most helpful?

Fixing production bugs: unfinished feature work stays in its folder while hotfixes can be made in a separate folder.
Testing multiple versions: You can run a stable branch and an experimental branch side by side.
Reviewing pull requests: one folder is used for the main code, another for checking out the branch being reviewed.
Reducing stash: unfinished changes do not need to be constantly stashed with git stash just to switch contexts.

The biggest benefit is not just saving time typing commands. Worktree reduces the risk of forgetting to restore changes, running tests on the wrong branch, or accidentally mixing hotfix work with new features.

Creating your first worktree

For example, if you are in the toko-online repository and want to create a hotfix folder next to the main folder, run:

git worktree add ../toko-online-hotfix hotfix

This command creates a new folder at ../toko-online-hotfix and checks out the hotfix branch inside it. The branch must already be available locally or recognizable by Git from remote references.

To create a new branch along with its worktree, use the -b option:

git worktree add -b perbaiki-checkout ../toko-online-checkout main

This means Git creates the perbaiki-checkout branch based on main and places it in the new folder.

After that, you can open two terminals or two editor windows:

toko-online for unfinished feature work.
toko-online-hotfix for urgent fixes.

Viewing and deleting worktrees

To see all worktrees connected to the repository, use:

git worktree list

The output will help you identify which folder is using a particular branch. This is important because Git usually prevents the same branch from being actively used in multiple worktrees at the same time. ([git-scm.com](https://git-scm.com/docs/git-worktree?utm_source=openai))

If the work is complete, delete the worktree with:

git worktree remove ../toko-online-hotfix

This command removes the linked worktree along with its working folder, but does not automatically delete the branch. If the branch is no longer needed, you can delete it separately with a command like git branch -d branch-name.

If the worktree folder has been manually deleted or moved without using Git commands, run:

git worktree prune

It is advisable to use git worktree remove first. prune is more suitable for cleaning up leftover metadata.

Things to keep in mind

Do not run two jobs on the same branch

One branch should only be active in one worktree. If you force the same branch to be used, the risk of conflicts and confusion increases. Use different branches for each work context.

Be mindful of dependencies and build files

Each worktree has its own working folder. In Node.js, PHP, Python, or Java projects, you may need to install dependencies or run build processes in each folder. Folders like node_modules, virtual environments, or compiled outputs are not automatically shared in a way that always makes sense.

Be cautious with local configurations

Configuration files not tracked by Git, such as .env, may not be available in the new worktree. Prepare a safe way to create local configurations without including secrets in the repository. Do not carelessly copy production credentials to experimental folders.

Do not delete folders carelessly while still in use

Git stores metadata to know the relationship between the main repository and linked worktrees. If a worktree is moved or deleted manually, its status may need to be repaired with git worktree repair or cleaned up using git worktree prune. ([git-scm.com](https://git-scm.com/docs/git-worktree?utm_source=openai))

A simple workflow to try

Keep the main repository for daily feature work.
Create a second worktree specifically for hotfixes or reviews.
Run tests in the folder corresponding to the active branch.
After the branch is merged or the work is complete, delete the worktree with git worktree remove.
Check the results with git worktree list to ensure no working folders are forgotten.

What does this mean for us?

Git worktree is not a feature that everyone must use. For small projects with a single simple workflow, switching branches normally may be sufficient. However, if you often handle multiple contexts at once—such as new features, bug fixes, and code reviews—worktree can make the process feel much more manageable.

The key is to treat each worktree as a clear workspace: one folder for one purpose. With that habit, you won't need to constantly stash changes just because there is another task that needs to take priority.

Sources & further reading

– Rio Yotto @rioyotto