Fix: Dirty Worktree Errors in Git

Git refuses to perform an operation and mentions a “dirty” worktree or working tree. This guide explains what that means and how to resolve it.

What Is a Dirty Worktree?

A dirty worktree (or dirty working tree) simply means you have uncommitted changes in your working directory. This includes:

• Modified tracked files— files that Git knows about but that have been edited since the last commit.
• Staged but uncommitted changes— files you have added to the index with git add but not yet committed.
• Deleted tracked files— tracked files that have been removed from the working directory.

You can check whether your worktree is dirty with git status:

$ git status
On branch feature/dashboard
Changes not staged for commit:
  modified:   src/app.tsx
  deleted:    src/old-utils.ts

Changes to be committed:
  new file:   src/new-component.tsx

If git statusshows any changes, the worktree is dirty. A clean worktree shows “nothing to commit, working tree clean.”

When This Error Appears

Many Git operations require a clean worktree because they modify files in your working directory. If you have uncommitted changes, those changes could be lost or create conflicts. Here are the most common situations:

During git merge or git pull

$ git pull origin main
error: Your local changes to the following files would be overwritten by merge:
  src/app.tsx
Please commit your changes or stash them before you merge.
Aborting

During git rebase

$ git rebase main
error: cannot rebase: You have unstaged changes.
error: Please commit or stash them.

During git checkout or git switch

$ git switch main
error: Your local changes to the following files would be overwritten by checkout:
  src/app.tsx
Please commit your changes or stash them before you switch branches.
Aborting

During git worktree remove

$ git worktree remove ../feature-worktree
fatal: cannot remove a dirty worktree; use --force to override

Solutions

Solution 1: Commit Your Changes

The most straightforward solution. If your work is in a usable state, commit it:

git add -A
git commit -m "WIP: save progress before merge"

# Now the operation will succeed
git pull origin main

You can always amend or squash this commit later with git commit --amend or interactive rebase.

Solution 2: Stash Your Changes

If you do not want to commit yet, stash your changes temporarily:

# Save all uncommitted changes to the stash
git stash

# Perform the operation
git pull origin main

# Restore your changes
git stash pop

To include untracked files in the stash:

git stash --include-untracked

Solution 3: Use --force (for worktree remove)

When removing a worktree that has uncommitted changes, you can force the removal:

# This will discard any uncommitted changes in the worktree
git worktree remove --force ../feature-worktree

Solution 4: Discard Unwanted Changes

If you genuinely want to throw away your local changes:

# Discard changes to tracked files
git checkout -- .

# Or using the newer restore command
git restore .

# Remove untracked files (careful!)
git clean -fd

# Now the worktree is clean
git status
# nothing to commit, working tree clean

Prevention

• Commit early and often. Small, frequent commits keep your worktree clean and make it easy to rebase or merge.
• Use worktrees instead of stash. If you frequently context-switch between branches, worktrees eliminate dirty-worktree errors entirely because each branch has its own directory.
• Use WIP commits.Commit half-done work with a “WIP” prefix. You can squash it later before pushing.
• Enable autostash for rebase. Set git config rebase.autoStash true to have Git automatically stash and restore changes during rebase operations.

git config --global rebase.autoStash true
git config --global merge.autoStash true