This error occurs when you try to switch branches while having uncommitted changes in files that differ between the current branch and the target branch. Git prevents the switch to avoid losing your work. You can resolve this by stashing, committing, or discarding your changes.
When you run `git switch` (or `git checkout`) to change branches, Git needs to update your working directory to match the target branch. If you have uncommitted changes in files that also have different content on the target branch, Git cannot safely proceed—it would need to overwrite your local modifications with the target branch's version. Git prioritizes data safety over convenience. Rather than silently losing your work, it stops and asks you to handle the uncommitted changes first. This is a protective mechanism, not a bug. The error lists the specific files that would be overwritten, helping you identify which changes need to be handled before switching.
First, understand what's happening. Check which files have uncommitted changes:
git statusLook at the files listed in the error message. These are the files that exist in different states on the target branch.
If you want to keep your changes and apply them later, use git stash:
git stash
git switch <branch-name>After switching, you can restore your changes:
git stash popIf you have multiple stashes or want to keep the stash after applying:
git stash list # View all stashes
git stash apply stash@{0} # Apply without removing from stashNote: If your stashed changes conflict with the new branch, you'll need to resolve merge conflicts after git stash pop.
If your changes are ready to be saved on the current branch:
git add <files>
git commit -m "WIP: description of changes"
git switch <branch-name>Or commit all tracked modified files:
git add -u
git commit -m "WIP: save work before switching"
git switch <branch-name>You can always amend or squash this commit later if needed.
Warning: This will permanently delete your uncommitted work.
If you're certain you don't need the changes, you can discard them:
# Discard changes in specific files
git checkout -- <filename>
# Or discard all uncommitted changes
git checkout -- .
# Then switch normally
git switch <branch-name>Alternatively, force the switch (same effect—loses your changes):
git switch --force <branch-name>
# or
git switch -f <branch-name>If you started work on the wrong branch and want to move your changes to the target branch:
git stash
git switch <target-branch>
git stash popIf the changes apply cleanly, you're done. If there are conflicts, Git will mark them and you'll need to resolve them manually.
Alternative using a temporary branch:
git stash branch <new-branch-name>This creates a new branch from where you stashed, applies the stash, and drops it if successful.
### Understanding When This Error Occurs
Git only blocks the switch when there's an actual conflict. If your modified files are identical on both branches (or don't exist on the target branch), Git allows the switch and carries your changes along.
### Using git switch vs git checkout
The git switch command (introduced in Git 2.23) is the modern way to change branches. The older git checkout command produces the same error:
error: Your local changes to the following files would be overwritten by checkoutBoth commands accept --force / -f to override the protection.
### Stash vs Commit: When to Use Which
Use stash when:
- Your changes are incomplete or experimental
- You need to quickly switch branches and come back
- You're not sure which branch the changes belong on
Use commit when:
- Your changes are complete enough to save
- You want a clear history of what was done
- You might need to reference or cherry-pick the changes later
### Handling Partial Changes
If you only want to stash some files:
git stash push -m "description" -- path/to/file1 path/to/file2Or interactively choose hunks to stash:
git stash push -p### The --merge Option
For complex situations, git switch --merge attempts a three-way merge between your changes, the current branch, and the target branch:
git switch --merge <branch-name>This can help in some cases but may result in merge conflicts that need resolution.
### Worktrees for Parallel Work
If you frequently need to work on multiple branches simultaneously, consider using Git worktrees:
git worktree add ../project-feature feature-branchThis creates a separate working directory for the other branch, avoiding switch conflicts entirely.
warning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server