Git refuses to switch branches when you have uncommitted changes that would be overwritten. This protects your work from being lost.

The Error

Attempting to switch branches:

bash
git checkout feature-branch

You see:

bash
error: Your local changes to the following files would be overwritten by checkout:
	src/app.js
	config/settings.json
Please commit your changes or stash them before you switch branches.
Aborting

Or with git switch:

bash
git switch feature-branch
bash
error: Your local changes to the following files would be overwritten by checkout:
	src/app.js
Please commit your changes or stash them before you switch branches.
Aborting

Why This Happens

Git protects uncommitted work. The target branch has different versions of files you've modified locally. Switching would overwrite your changes without a way to recover them.

Common scenarios:

  • You started working on the wrong branch
  • You made experimental changes and want to switch contexts
  • Someone else committed to the file you're editing
  • Auto-generated files have local modifications

Diagnosis Steps

Check what's modified: ``bash git status

Shows: `` On branch main Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git restore <file>..." to discard changes in working directory) modified: src/app.js modified: config/settings.json

See the actual changes: ``bash git diff

Shows line-by-line differences from the last commit.

Check specific file: ``bash git diff src/app.js

See if changes are staged: ``bash git diff --cached

Staged changes would also be affected.

Solution 1: Stash Changes Temporarily

Save your work and switch:

bash
git stash push -m "Work in progress on main"

Output: `` Saved working directory and index state On main: Work in progress on main

Switch branches: ``bash git checkout feature-branch

Later, restore your changes: ``bash git checkout main git stash pop

Or apply without removing from stash: ``bash git stash apply

Solution 2: Commit Changes

If the work is meaningful, commit it:

bash
git add src/app.js config/settings.json
git commit -m "WIP: Configuring app settings"

Now switch branches: ``bash git checkout feature-branch

Your work is safely stored on the original branch.

Solution 3: Discard Local Changes

If changes are unwanted or easily recreated:

bash
git restore src/app.js config/settings.json

Or discard all changes: ``bash git restore .

Now switch: ``bash git checkout feature-branch

Warning: This permanently deletes uncommitted changes.

Force switch, bringing changes with you:

bash
git checkout --force feature-branch

Or: ``bash git checkout -f feature-branch

Warning: This discards local changes to files that differ between branches. Files that are the same in both branches keep your modifications. Use with caution.

Solution 5: Merge Instead of Checkout

If you want the changes from both branches:

bash
git add .
git commit -m "Local changes"
git merge feature-branch

Solution 6: Create New Branch with Changes

Keep your changes but on a new branch:

bash
git checkout -b feature-wip

This creates and switches to a new branch with your changes.

Solution 7: Checkout Specific Files

If you only need to discard changes to certain files:

bash
git checkout feature-branch -- src/app.js

This brings the file from the other branch to your current working directory.

Handling Merge Conflicts After Stash Pop

If stash pop causes conflicts:

bash
git stash pop

Shows: `` CONFLICT (content): Merge conflict in src/app.js

Resolve the conflict markers, then: ``bash git add src/app.js git stash drop # Remove the stash entry

Verification

Confirm you're on the target branch: ``bash git branch

Current branch is marked with *.

Check status after switching: ``bash git status

Should show clean state or expected changes.

Verify stash contents: ``bash git stash list

Shows saved stashes: `` stash@{0}: On main: Work in progress on main

Handling Specific Scenarios

Untracked files that would be overwritten:

bash
error: The following untracked working tree files would be overwritten by checkout:
	src/new-file.js

Options:

```bash # Remove untracked file rm src/new-file.js

# Or force checkout (removes the file) git checkout -f feature-branch ```

Binary file conflicts:

bash
error: Your local changes to the following files would be overwritten by checkout:
	assets/logo.png

Stash or commit binary files the same way: ``bash git stash push -m "Logo work"

Prevention Strategies

Check status before switching: ``bash git status

Make this a habit before checkout or switch.

Use git switch for clarity: ``bash git switch feature-branch

git switch is more explicit about branch operations and won't accidentally restore files.

Create feature branches early: ``bash git checkout -b feature/new-feature

Start new work on dedicated branches from the beginning.

Commit frequently: ``bash git add -p # Stage portions git commit -m "WIP: Partial feature"

Smaller commits are easier to manage than large uncommitted changes.

Stash Best Practices

Name your stashes: ``bash git stash push -m "Descriptive message about the work"

View stash contents: ``bash git stash show -p stash@{0}

Apply specific stash: ``bash git stash apply stash@{2}

Clear all stashes: ``bash git stash clear

Keep staged changes separate: ``bash git stash push -p # Stash only staged changes