Mastering Git Worktree

Why Git Worktree Matters

Git Worktree allows you to check out multiple branches at the same time in different directories. It's the ultimate tool for developers who hate git stash.

Traditional Git workflows force you to choose: either stash your work and switch branches, or make a temporary commit just to work on something else. This adds friction to your development process and creates messy commit histories. Git Worktree eliminates this problem entirely.

Whether you're working on a feature while handling an emergency hotfix, testing multiple branches in parallel, or building on the main branch while reviewing a colleague's PR—worktrees make context switching seamless.

Step 1: Create the Worktree

You're on feature-alpha, but a bug appears in main. Don't stash! Just add a new tree:

$ git worktree add ../hotfix-folder main
Preparing worktree (checking out 'main')
HEAD is now at a1b2c3d Fix layout issue

That's it! You now have a second directory, ../hotfix-folder, with the main branch checked out. Your original feature-alpha work remains untouched.

Step 2: The Workflow Simulator

Notice how your physical file system changes. You now have two distinct environments:

Switch to the new folder to work. This will not touch your files in /my-project:

$ cd ../hotfix-folder
$ npm install  # Only affects this folder!
$ git add . && git commit -m "Emergency fix"
$ git push origin main

After your fix is merged, switch back to your feature work. All your changes are exactly where you left them, no stash pop needed:

$ cd ../my-project
$ npm run dev  # Continue exactly where you left off

Step 3: Should you delete it?

Yes. Once your task is done, you should remove the worktree. This "unlocks" the branch so it can be used elsewhere and keeps your disk clean.

Go back to your main project and tell Git to prune the linked tree:

$ cd ../my-project
$ git worktree remove ../hotfix-folder

Note: Git won't let you delete a worktree with uncommitted changes unless you use --force. Safe!

Comparison: Isolation Benefits

Here's how worktrees compare to the standard branch-switching workflow:

"Git Worktree has completely transformed how our team handles parallel development. No more stash conflicts, no more accidental commits—just clean, isolated workspaces."

Best Practices

• Use consistent naming: Name worktrees after their purpose (e.g., hotfix-layout-bug, feature-auth-system)
• Clean up promptly: Remove worktrees after you're done to avoid clutter and free up disk space
• List active worktrees: Use git worktree list to see all active directories at a glance
• Avoid nested worktrees: Create worktrees as siblings to your main project, not nested inside it
• Shared .git directory: Worktrees share the same repository history, so all commits are visible across all trees
• Branch locking: Remember that a branch can only be active in one worktree at a time—Git prevents mistakes here