No More Back-and-Forth Checkout: How to Use…

Switching branches with git checkout or git switch is usually sufficient for daily tasks. However, the workflow can become cumbersome when you are working on an unfinished feature and need to quickly fix a bug in another branch. Local changes need to be saved, dependencies may change, and the work context can easily get mixed up.

Git has a feature called worktree for situations like this. Simply put, a single repository can have multiple working folders that run concurrently. Each folder can use a different branch while still sharing the same Git history.

What is Git Worktree?

According to the official Git documentation, a worktree is an additional working directory connected to the same repository. The main repository retains one working folder, and you can add linked worktrees for other branches.

Imagine the repository as a large library. Branches are the version paths of books, while worktrees are several reading tables. You can open books from different paths at each table without having to close and switch books at the same table.

What is shared are the repository history, commits, branches, and remotes. Meanwhile, the working files, staging area, and uncommitted changes are kept separately in each worktree.

When is Worktree More Useful than Stash?

git stash is still useful for temporarily saving changes. However, stash requires you to leave the work context before switching branches. When you return, you need to reapply those changes and may encounter conflicts.

Worktree is more suitable if you often work on two contexts simultaneously, for example:

The main feature is not finished, but there is a production bug that needs to be fixed immediately.
You want to review a pull request without disrupting local work.
You need to compare two versions of an application directly.
The testing or build process takes a long time, while you want to work on another task.
You want to open the documentation branch and the code branch in two separate editor windows.

This does not mean that worktree is always better. Each additional folder may require its own configuration, dependencies, and storage space. Use it when the benefits of keeping multiple contexts open outweigh the management costs.

Creating Your First Worktree

Suppose you are in the main repository folder and want to create a worktree for a bug fix:

git worktree add ../project-hotfix bugfix/payment-validation

This command creates a folder project-hotfix one level above the current repository and checks out the branch bugfix/payment-validation inside it.

If the branch does not exist, you can ask Git to create a new branch at the same time:

git worktree add -b feature/report ../project-report main

This example creates a new branch named feature/report based on main, then places it in the folder project-report.

After that, your folder structure will look something like this:

projects/├── project/           # main worktree, e.g., main branch├── project-hotfix/    # bugfix/payment-validation branch└── project-report/    # feature/report branch

You can open each folder in the editor separately. In VS Code, each worktree can appear as a different repository in the Source Control view, allowing multiple working windows to be opened without constantly switching branches.

Commands to Remember

To see all worktrees connected to the repository:

git worktree list

The output will display the folder locations, the commit currently in use, and the active branch. This command helps when you forget which branch is in a particular folder.

If the work is done, remove the worktree with:

git worktree remove ../project-hotfix

Run this command after ensuring there are no local changes still needed. If the worktree folder is deleted manually, related metadata may be left behind. To clean up data from worktrees that no longer exist, use:

git worktree prune

Git also prevents a local branch from being checked out in more than one worktree at the same time. This rule is important because two folders writing to the same branch can create confusing statuses and histories.

Common Surprises for New Users

Dependencies Are Not Automatically Ready

Worktree separates working folders, but files ignored by .gitignore, such as node_modules, .env files, or build outputs, are usually not copied over. As a result, you may need to run npm install again, copy local configurations, or set up environment variables.

This is actually a safe behavior: secrets and local machine configurations should not automatically appear in every folder. If using VS Code, there are settings to specify which files are safe to copy to new worktrees, but use this with caution—especially for files containing tokens or credentials.

Worktree Is Not a Security Sandbox

Worktree only separates files and branches. It is not a security boundary that prevents code from accessing other files on the computer, network, or external services. If you run untrusted code, still use appropriate security measures, such as containers, accounts with limited permissions, or separate testing environments.

Do Not Create Too Many Worktrees

Having several worktrees is practical, but too many folders can cause dependencies, caches, and build outputs to consume space. Use clear folder naming, and remove worktrees that are no longer active.

A Simple Workflow to Try

Keep the main repository for primary work or the main branch.
Create a worktree specifically for hotfixes that need immediate attention.
Open that worktree in a separate editor window.
Commit and push changes as usual from that folder.
Once the branch is merged and no longer needed, remove the worktree with git worktree remove.

What Does This Mean for Us?

Git worktree is not a feature that everyone must use. However, for developers who often handle multiple parallel tasks, this feature can reduce the recurring minor disruptions: stashing, checking out, waiting for builds to finish, and then returning to the work context.

Start with a clear case, such as creating a hotfix folder next to the main repository. Once you are familiar with git worktree list and git worktree remove, you can assess whether this multi-folder workflow makes the process tidier or adds to the burden. The official Git documentation and the worktree guide in VS Code can be used to tailor the workflow to project needs.

Sources & Further Reading

– Rio Yotto @rioyotto