Git Worktrees Explained Simply: A Practical Guide (With Real Use Cases)

If you’ve ever struggled with switching branches, stashing changes, or working on multiple features at once — Git worktrees can completely change your workflow.

This guide explains what worktrees are, how they work, and how to use them correctly, with practical examples.

---

🌳 What is a Git Worktree?

A Git worktree allows you to have multiple working directories (folders) for the same repository.

Each worktree:

• Has its own checked-out branch
• Shares the same Git history and .git data
• Works independently from other worktrees

---

🧠 Why Worktrees Exist

Normally in Git:

• One repo = one folder = one active branch

This creates problems:

• You can’t work on multiple features at once
• You keep switching branches
• You rely on git stash (messy and risky)

👉 Worktrees solve this by giving you multiple folders for the same repo

---

📁 Example

Main repo:

my-project/   → main branch

Create a worktree:

my-project/        → main
feature-login/     → feature-login

Now you can:

• Work on main in one folder
• Work on feature-login in another

---

⚙️ Core Command

Create a new worktree + branch

git worktree add ../feature-login -b feature-login

What this does:

• Creates folder: ../feature-login
• Creates branch: feature-login
• Automatically checks out that branch in the new folder

---

📌 Important: Path vs Branch

git worktree add <path> -b <branch>

Part	Meaning
<path>	Folder name (worktree)
<branch>	Git branch name

Example:

git worktree add ../abc -b my-feature

• Folder = abc
• Branch = my-feature

👉 They don’t have to match

---

🔍 What Happens Internally?

Worktrees are not full copies of the repo.

Shared:

• Git history
• Commits
• Objects
• .git database

Separate:

• Working files
• Current branch
• Staging area

Inside worktree:

feature-login/.git → points to main repo

---

❗ Important Behavior (Very Common Confusion)

Each folder has its own branch

• Parent folder stays on main
• Worktree folder is on feature-login

👉 They are independent

---

🧪 Example

cd my-project
git branch

* main

cd ../feature-login
git branch

* feature-login
  main

---

🔁 Typical Workflow

# Create new feature workspace
git worktree add ../feature-x -b feature-x

# Move into it
cd ../feature-x

# Work normally
git add .
git commit -m "Add feature"

# Push
git push origin feature-x

---

⚠️ Rules to Remember

1. One branch = one worktree

You cannot check out the same branch in two folders.

---

2. Always tied to a branch

Every worktree must have a branch.

---

3. Don’t delete manually

Wrong:

rm -rf ../feature-x

Correct:

git worktree remove ../feature-x

---

🔁 Common Mistakes

❌ Mistake 1: Forgetting -b

git worktree add ../feature-x

👉 This just uses current branch (no new branch)

---

❌ Mistake 2: Checking branch in wrong folder

Users check in parent folder and think it didn’t switch.

👉 Always check inside the worktree folder.

---

❌ Mistake 3: Thinking it’s a full repo copy

It only looks like a full repo — it’s actually lightweight.

---

⚔️ Worktree vs Clone

Feature	Worktree	Clone
Disk usage	Low	High
Speed	Fast	Slower
Git history	Shared	Separate
Independence	Partial	Full

---

🤖 Why Tools Like Claude Code Use Worktrees

AI tools use worktrees to:

• Work on multiple features in parallel
• Avoid breaking your main branch
• Create clean PRs
• Isolate changes safely

---