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

GitBEGINNERLOWUpdated Dec 6, 2025· 465 views

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.

Quick fix

Fixes error: Your local changes to the following files would be overwritten by checkout

# See all uncommitted changes
git status

# See the specific differences in modified files
git diff

# See staged changes
git diff --cached
  1. Check which files are blocking the checkout
  2. Option 1: Stash your changes (recommended)
  3. Option 2: Commit your changes first
  4. Option 3: Discard your changes (use with caution)
git — error
# See all uncommitted changes
git status
# See the specific differences in modified files
git diff
# See staged changes
git diff --cached
error: Your local changes to the following files would be overwritten by checkout

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.

Typical symptoms

  • Unable to switch branches with 'git checkout' or 'git switch'
  • Error message lists specific files that would be overwritten
  • Branch switch fails even though you expected no conflicts
  • 'git status' shows modified files in your working directory
  • Cannot checkout a specific commit or tag
  • Pull request review workflow blocked by checkout error
  • IDE branch switching fails with Git error

Common causes

  1. Uncommitted changes exist in files that differ between branches
  2. Staged but uncommitted changes conflict with target branch
  3. File was modified locally and also changed in the target branch
  4. Auto-generated files (like build artifacts) were modified locally
  5. Line ending changes between branches conflict with local edits
  6. IDE or editor created swap/backup files in the repository
  7. Git hooks or formatters modified files after your last commit

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

Frequently asked questions

What does "error: Your local changes to the following files would be overwritten" mean?
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.
How do I fix "error: Your local changes to the following files would be overwritten"?
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 causes "error: Your local changes to the following files would be overwritten"?
Uncommitted changes exist in files that differ between branches Staged but uncommitted changes conflict with target branch File was modified locally and also changed in the target branch
Is the "error: Your local changes to the following files would be overwritten" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading