How to fix error: Your local changes to the following files would be overwritten by checkout in Git

GitBEGINNERLOW

This Git error occurs when you try to switch branches while having uncommitted changes that conflict with files in the target branch. Git prevents the checkout to protect your work. You can resolve it by stashing, committing, or discarding your changes.

What this error means

This error occurs when you run `git checkout` or `git switch` to change branches, but you have uncommitted local changes in files that would be modified or replaced by the checkout operation. Git prevents the branch switch to avoid silently overwriting your work. When Git performs a checkout, it needs to update your working directory to match the target branch. If a file exists in both branches but with different contents, and you have local modifications to that file, Git cannot safely proceed. It would have to choose between keeping your changes (making the checkout incomplete) or discarding them (losing your work). This is a protective mechanism. Git is explicitly warning you that continuing would result in lost work, and it refuses to proceed until you explicitly decide what to do with your uncommitted changes.

How to fix "error: Your local changes to the following files would be overwritten by checkout"

1Check which files are blocking the checkout

First, identify exactly what changes are preventing the checkout:

bash

# See all uncommitted changes
git status

# See the specific differences in modified files
git diff

# See staged changes
git diff --cached

The error message from Git will list the specific files. Review them to understand if these changes are important to keep.

2Option 1: Stash your changes (recommended)

If you want to keep your changes but switch branches temporarily, use git stash:

bash

# Stash all uncommitted changes
git stash

# Now switch branches
git checkout feature-branch

# When you return to your original branch, restore changes
git checkout original-branch
git stash pop

Stash with a descriptive message:

bash

git stash push -m "WIP: working on login feature"

Include untracked files in the stash:

bash

git stash push -u -m "Including new files"

The git stash pop command applies your stashed changes and removes them from the stash. Use git stash apply instead if you want to keep the stash for later use.

3Option 2: Commit your changes first

If your changes are ready to be committed, do so before switching branches:

bash

# Stage your changes
git add <modified-files>
# Or stage all changes
git add .

# Commit with a descriptive message
git commit -m "feat: implement user authentication"

# Now switch branches safely
git checkout feature-branch

For work-in-progress commits:

bash

# Create a WIP commit you can amend later
git add .
git commit -m "WIP: save progress before switching branches"

# Later, when you return, you can amend or squash this commit
git commit --amend -m "Completed feature"

4Option 3: Discard your changes (use with caution)

If you don't need your local changes, you can discard them:

bash

# Discard changes to specific files
git checkout -- path/to/file.txt

# Or using the newer restore command
git restore path/to/file.txt

# Discard ALL uncommitted changes (dangerous!)
git checkout -- .
# Or
git restore .

Before discarding, review what you're losing:

bash

git diff path/to/file.txt

Warning: This permanently deletes your uncommitted work. There is no way to recover discarded changes that were never committed or stashed.

5Option 4: Force the checkout (destructive)

You can force Git to switch branches, discarding all conflicting changes:

bash

# Force checkout - WILL LOSE uncommitted changes
git checkout -f feature-branch
# Or
git checkout --force feature-branch

When using git switch:

bash

git switch -f feature-branch
# Or
git switch --force feature-branch

Warning: This is equivalent to discarding changes and then checking out. Only use this when you're certain you don't need any of your local modifications.

6Option 5: Reset to a clean state

For a complete reset to match the current branch before switching:

bash

# Hard reset discards ALL changes (staged and unstaged)
git reset --hard HEAD

# Now checkout will work
git checkout feature-branch

To also remove untracked files:

bash

# Dry run first to see what would be deleted
git clean -n

# Remove untracked files
git clean -f

# Remove untracked files AND directories
git clean -fd

Warning: git reset --hard and git clean -f are destructive. There is no undo. Consider using git stash first as a safety net.

7Handling the error in specific scenarios

In VS Code or IDE:
Most IDEs show a dialog offering to stash or discard changes. Choose "Stash" to preserve your work.

During git pull:
If this error occurs during git pull, the same solutions apply:

bash

git stash
git pull
git stash pop

With multiple files:
When many files are affected, stashing is usually the cleanest solution:

bash

# Stash everything including untracked files
git stash push -u -m "Stashing before branch switch"

# Check stash list
git stash list

# Apply specific stash if needed
git stash apply stash@{0}

Advanced notes

### Understanding Git's Working Directory Protection

Git's checkout process involves three trees:
1. HEAD: The last commit on the current branch
2. Index (Staging Area): What would go into the next commit
3. Working Directory: Your actual files

When you checkout a branch, Git must update all three. If your working directory has changes that would conflict with the target branch, Git refuses to proceed.

### When Git Allows Checkout Despite Local Changes

Git will allow checkout if your local changes:
- Are to files that don't exist in the target branch
- Are identical to the target branch's version
- Are in files that are the same in both branches

### Stash vs Commit for WIP

| Approach | Pros | Cons |
|----------|------|------|
| Stash | Quick, doesn't pollute history | Can be forgotten, merge conflicts on pop |
| WIP Commit | Part of history, can be pushed | Requires cleanup later (amend/squash) |
| Feature Branch | Clean separation | Overhead for tiny changes |

### Best Practice: Use git stash apply Instead of pop

bash

# Apply but keep the stash
git stash apply

# Only drop the stash after confirming everything works
git stash drop

This protects against losing changes if conflicts occur during stash application.

### Preventing This Error

1. Commit frequently: Small, frequent commits reduce the chance of conflicts
2. Use feature branches: Keep unrelated work separate
3. Check status before switching: Make git status a habit
4. Configure git to autostash on rebase:

bash

git config --global rebase.autoStash true

### Worktrees: Switch Without Stashing

Git worktrees let you have multiple branches checked out simultaneously:

bash

# Create a new worktree for a different branch
git worktree add ../project-feature feature-branch

# Work in that directory without affecting your main checkout
cd ../project-feature

# Remove when done
git worktree remove ../project-feature

### Line Ending Issues

If you're seeing this error unexpectedly, line endings might be the culprit:

bash

# Check your line ending settings
git config core.autocrlf

# Normalize line endings
git add --renormalize .

### IDE Integration

Most modern IDEs handle this gracefully:
- VS Code: Git sidebar shows modified files; offers stash option
- IntelliJ/WebStorm: Shelve changes (similar to stash)
- Sublime Merge: Visual stashing and branch switching

How to fix error: Your local changes to the following files would be overwritten by checkout in Git

What this error means

Typical symptoms

Common causes

How to fix "error: Your local changes to the following files would be overwritten by checkout"

Advanced notes

Related errors

Official resources & further reading