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:
Commitis the edition/version of the bookBranchis a bookmark tucked into a pageWorktreeis 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!