Fix 'Your local changes would be overwritten by checkout' in Git

What this error means

Git stops you from switching branches when files in your working tree differ from HEAD and would be overwritten by the target branch. This prevents data loss.

Typical message:

error: Your local changes to the following files would be overwritten by checkout:
  app.py
Please commit your changes or stash them before you switch branches.
Aborting

Quickstart (safe fixes)

1. Commit your work-in-progress to your current branch:
   • git add -A
   • git commit -m "WIP"
   • git checkout target-branch
2. Or stash changes, switch, then re-apply:
   • git stash push -m "WIP before switch"
   • git checkout target-branch
   • git stash apply
3. If you only want to stash some files:
   • git stash push -- path/to/file1 path/to/dir
4. If the error is about untracked files:
   • git stash push -u
   • or move/rename them; or dry-run clean: git clean -dn

Only use force options if you intend to discard work.

Minimal working example

Reproduce the error and fix it safely.

# Start a demo repo
mkdir demo && cd demo
git init -b main
printf 'v1\n' > app.txt
git add app.txt
git commit -m "v1"

# Create a feature branch and edit the file
git checkout -b feature
printf 'v2-feature\n' > app.txt

# Attempt to switch back; this errors
git checkout main
# => error: Your local changes ... would be overwritten by checkout

# Safe resolution: stash, switch, re-apply
git stash push -m "WIP feature change" app.txt
git checkout main
# Work on main... then later
git stash apply  # brings back your change onto main

Why it happens

• Your working tree has modifications that conflict with the target branch’s version of those files.
• Git protects you from losing those modifications during checkout.
• Similar errors can occur for untracked files that would be overwritten.

Choose the right approach

Step-by-step: common scenarios

1. I want to keep my edits and switch branches now
   • Use stash:
     • git stash push -m "WIP before switch"
     • git checkout target
     • git stash apply
   • Or commit WIP and switch:
     • git add -A && git commit -m "WIP"
     • git checkout target
2. I only changed a few files and I’m fine discarding them
   • Preview changes: git status; git diff
   • Discard selectively: git restore --source=HEAD -- path/to/file
   • Then: git checkout target
3. The error mentions untracked files
   • Save them too: git stash push -u
   • Or preview deletions: git clean -dn
   • If safe: git clean -fd
4. I frequently need two branches at once (CI/CD, hotfixes)
   • Use worktrees:
     • git worktree add ../repo-hotfix hotfix
     • Edit in ../repo-hotfix without touching the current tree

Handling conflicts after applying stash

• If git stash apply results in conflicts:
  • Resolve with your usual merge tools.
  • git add <resolved files>
  • git commit (if desired) to record the resolution.
• To abandon the applied stash without committing, reset files: git restore --staged -W . then re-apply carefully or re-stash.

Pitfalls and safety tips

• reset --hard and clean -fd are destructive. Always preview with git status, git diff, and git clean -dn.
• Stash is local-only. It won’t protect you if you clone elsewhere. Consider committing WIP to a private branch.
• Large stashes can be slow; prefer pathspec-limited stashes: git stash push -- path/to/dir.
• Line-ending or permission-only changes may trigger the error. Normalize with:
  • git config core.autocrlf input|true (team-dependent)
  • git config core.filemode false (if permission flips are noise)
• Submodules: changes inside submodules also block checkout. Commit or stash inside each submodule, or update the superproject pointer carefully.

Performance notes (DevOps scale)

• Use git worktree for parallel branches to avoid repeated stash/apply cycles during releases and hotfixes.
• Limit stash scope with pathspecs to reduce I/O: git stash push -- src/.
• For huge repos, avoid staging everything unnecessarily. Use git add -p or targeted paths.
• Run background maintenance on developer machines and build agents:
  • git maintenance start
  • Keeps commit-graph and packfiles optimized.
• Sparse-checkout (git sparse-checkout set ...) reduces working-set size and speeds up operations that touch the working tree.

Tiny FAQ

• Can I force checkout and discard my changes?
  • Yes: git checkout -f target or git reset --hard HEAD; then checkout. This deletes uncommitted work.
• How do I keep my edits but move them to a new branch?
  • git switch -c my-wip-branch creates a branch pointing to current HEAD and keeps your working changes.
• Stash or commit?
  • Commit for work you want in history and to share; stash for temporary, local changes.
• What about the error for untracked files?
  • Use git stash -u to save them, or git clean -dn to preview and git clean -fd to remove if safe.