Why git stash every branch switch? What is Git Worktree? Differences between Git Worktree and Git Branch? How to build a high-efficiency multi-threaded workflow with Git Worktree?

Sat, 08 Aug 2026 08:29:00 +0800

Have you ever encountered this situation? You are in the middle of developing a complex feature when an urgent bug suddenly pops up that requires immediate fixing.

To switch branches, you reluctantly run git stash to hide your half-finished code. After fixing the bug and switching back, you carefully run git stash pop, sometimes even triggering painful code conflict nightmares.

In fact, Git has long provided a powerful tool to solve this pain point: Git Worktree.

Say goodbye to messy branch switching and stashing, and embrace multi-threaded development with Worktree

This article guides you through its core mechanics and practical real-world usage.

What is the difference between Git Worktree and Git Branch?

To understand Git Worktree, let us first clarify how it differs from Git Branch.

Think of version control like reading a physical book:

Commit is the edition/version of the book
Branch is a bookmark tucked into a page
Worktree is the desk where you spread open the book

In the traditional approach, we only have one desk. Whenever we want to switch bookmarks, we must pack up all modified pages on the desk or hide them in a drawer (which is git stash).

Git Worktree, on the other hand, allows you to own multiple independent working desks simultaneously.

Comparison	Git Branch	Git Worktree
Workspace Concept	Shares a single physical working directory	Owns multiple independent working directories
Cost of Switching	Requires committing, stashing, or staging changes	No stashing required; simply switch directories
Isolation & Safety	Uncommitted files can cause conflicts or leftover artifacts	Completely isolated directories; changes do not interfere
History Log	Shares Git Commit history and branches	Shares Git Commit history and branches

Different worktrees have completely independent active branches, staging areas, and uncommitted modifications, but they share all Commit history and branch records.

Branch is a version bookmark, while Worktree is a physical working desk

This way, whenever you need to switch tasks, you simply open another directory folder without touching your current work state at all.

How to get started with Git Worktree?

When adopting Git Worktree in actual projects, thoughtful directory organization makes development much smoother.

It is recommended to keep the original git clone project directory as a clean main headquarters, while placing newly created Worktree directories outside the main repository folder (e.g., ../my-app-worktrees), preventing dev tools from recursive directory scanning errors.

Common command workflows are as follows:

Workflow	Command
1. Create a new Worktree along with a new branch	`git worktree add ../my-app-worktrees/feature-login -b feature-login`
2. View all active Worktrees	`git worktree list`

Git Worktree is especially well-suited for managing development tasks for an AI Agent.

You can assign a separate Worktree directory to an AI Agent for unrestricted code edits and testing, while human developers perform code reviews and testing in another Worktree.

Give AI Agents an isolated Worktree to run AI development and human code reviews in parallel

Both operate in their respective physical directories, keeping processes secure and clear.

How to merge and safely clean up after finishing development?

Once you finish development in an isolated Worktree, how should you merge the results and perform cleanup?

Keep an important concept in mind: Worktree directories themselves do not need merging; what truly needs merging is the Branch.

You only need to return to the main desk directory and execute git merge on the corresponding feature branch to complete integration.

For cleanup, follow the standard two-step process:

Step	Command
1. Remove the Worktree physical directory	`git worktree remove ../my-app-worktrees/feature-login`
2. Delete the completed feature branch	`git branch -d feature-login`

Remove the Worktree directory first, then delete the Branch

Always use the git worktree remove command for cleanup instead of manually deleting folders in your file explorer.

What are common pitfalls when using Git Worktree?

Although Git Worktree is extremely convenient, there are several common landmines to keep in mind.

Pitfall 1: Uncommitted changes will be lost

Although deleting a Worktree does not delete the Branch itself, forcibly deleting a Worktree directory with uncommitted changes will permanently wipe out those modifications.

Pitfall 2: Branch occupation conflicts

Git’s safety mechanism does not allow checking out the same Branch in two different Worktrees simultaneously. If you try checking out a branch already in use in a second Worktree, Git will block the action and throw an error.

Forcibly removing a Worktree causes uncommitted changes to be lost

By mastering these characteristics and principles, you can easily avoid these traps.

Conclusion

With Git Worktree, we can completely leave messy branch switching and git stash behind, achieving true multi-threaded development.

Next time you face an urgent bug fix, work on multiple features concurrently, or assign coding tasks to an AI Agent, try opening a fresh working desk!

Reference

Git - git-worktree Documentation

Git Worktree on Dev TLDRLSS