How to fix "fatal: Untracked working tree file … would be overwritten by checkout" in Git

Overview

This error happens when you try to switch branches (checkout/switch) and Git sees an untracked file in your working tree that would be overwritten by a tracked file from the target branch. Git stops to protect your untracked content from loss.

Typical trigger: you created a file locally that the target branch already tracks at the same path.

Minimal working example (MWE)

Reproduce the error safely in a throwaway repo.

# Start clean
mkdir demo-checkout-overwrite && cd demo-checkout-overwrite
git init

# Create main commit
printf "hello\n" > README.md
git add README.md
git commit -m "init"

# Create a branch that tracks config.yml
git switch -c feature
printf "tracked\n" > config.yml
git add config.yml
git commit -m "add tracked config.yml"

# Go back to main and create an untracked config.yml
git switch main
printf "local\n" > config.yml  # untracked in main

# Try switching to feature; this should fail
git switch feature
# fatal: Untracked working tree file 'config.yml' would be overwritten by checkout

Quickstart: Fix it fast

Pick one action based on whether you want to keep or discard the untracked file.

• Keep the untracked file (safe):
  • Stash including untracked: git stash -u then git switch <branch> then git stash pop.
  • Or move it aside: mv path path.backup then switch.
• Discard the untracked file (dangerous):
  • Preview then clean: git clean -nd (preview), git clean -fd (delete), then switch.
  • Or force switch: git switch -f <branch> (overwrites conflicting untracked files).
• Avoid switching entirely (just need a file from the other branch):
  • git show <branch>:path/to/file > file.from-branch.

Step-by-step resolution

1. Identify the conflicting paths

• Git’s error prints each offending file path. If many files are involved and you want to preview:

# Show untracked files in current worktree
git ls-files --others --exclude-standard | sort > /tmp/untracked.txt

# Show tracked files in the target branch
TARGET=feature
git ls-tree -r --name-only "$TARGET" | sort > /tmp/tracked-target.txt

# Intersect to see conflicts
comm -12 /tmp/untracked.txt /tmp/tracked-target.txt

1. Decide whether to keep or discard your untracked file(s)

• Keep if the file contains useful local changes or environment-specific config.
• Discard if it’s generated, temporary, or safe to recreate.

1. If keeping, choose one:

• Stash including untracked, then switch and re-apply:

git stash -u -m "save untracked before switch"
git switch feature
# Later, bring it back (may merge/override depending on content)
git stash pop

• Move aside, then switch:

mv config.yml config.yml.local
git switch feature
# Optionally, reconcile later (rename or merge content)

• Commit on a separate branch and reconcile later (advanced):

git switch -c keep-local
git add config.yml && git commit -m "keep local config"
# Merge or cherry-pick strategically later; consider renaming to avoid path conflicts

1. If discarding, choose one:

• Clean untracked files (safer with dry-run first):

git clean -nd     # preview what would be removed
git clean -fd     # remove untracked files and dirs
git switch feature

• Force the switch:

git switch -f feature  # or: git checkout -f feature

Warning: Both options irreversibly remove or overwrite untracked files. Only use when you’re sure they are disposable.

1. Verify

git status       # ensure you’re on the desired branch

Common commands at a glance

Pitfalls and gotchas

• .gitignore doesn’t fix the immediate error. Ignore rules don’t change existing files in your working tree.
• git stash without -u does not include untracked files. Use -u (or -a to include ignored files).
• Force options (-f) and git clean -fd are destructive. Use -n to preview.
• After git stash pop, you may get merge conflicts if the target branch already tracked the same path with different content.
• On case-insensitive filesystems (e.g., default Windows/macOS), subtle path collisions can also cause similar issues.

Performance notes

• Stashing large untracked trees (git stash -u) writes blob objects; runtime and disk usage grow with file size. Prefer moving a few files aside if only a handful conflict.
• git clean -nd scans the working tree; in huge repos with many untracked files, this can be slow. Narrow the scope: git clean -nd path/.
• For repeated environment-specific files, use a persistent local filename (e.g., config.local.yml) committed to .gitignore early, to avoid recreating conflicts.
• If you frequently need different working copies of the same repo, consider git worktree add ... to avoid clobbering files when switching branches.

Prevent it next time

• Standardize local-only filenames (e.g., *.local.*) and ignore them from the start.
• Avoid creating untracked files at paths that the repo tracks on other branches; prefer alternate names.
• Use feature branches that add files under stable directories to reduce path overlap.
• Keep your working tree tidy: remove generated artifacts or direct them to build/output directories ignored by Git.

Tiny FAQ

• Why does Git block the checkout? To prevent loss of untracked work by overwriting it with tracked files from the target branch.

• What’s the safest universal fix? git stash -u before switching, then git stash pop after. Review conflicts if any.

• Can .gitignore prevent this? It can prevent future noise, but it does not resolve an existing untracked file that already conflicts.

• I only need a file from another branch. Do I need to switch? No. Use git show <branch>:path > path.copy to copy it without switching.

• How do I preview what would be removed by cleaning? git clean -nd shows the untracked files and directories that would be deleted without actually deleting them.