[Git] Error: The following untracked working tree files would be overwritten by checkout — Switching branches safely — How to Fix It

Summary

error: The following untracked working tree files would be overwritten by checkout means Git has detected local files not tracked by version control that would be replaced by files from the branch you’re trying to switch to. Git halts the operation to prevent accidental data loss.

Context

This usually happens when untracked files in your working directory share the same names or paths as tracked files in another branch. For example, you created a local file that also exists in the branch you’re checking out — Git refuses to overwrite it silently.

Probable Cause

  • Untracked files overlap with tracked files in the target branch.
  • Temporary or generated files conflict with existing repository files.
  • Branch switch attempted before committing or stashing work.
  • Residual build or cache files not ignored via .gitignore.

Quick Fix

  1. List untracked files: 
    git status
  2. If you want to keep them, commit first: 
    git add .
git commit -m "Save work before switching branches"
  3. If you want to keep but not commit, stash them: 
    git stash push -m "temp untracked" --include-untracked
  4. Now switch branches safely: 
    git checkout branch-name
  5. Restore stashed files (optional): 
    git stash pop
  6. If files are disposable, delete them: 
    git clean -fd   # ⚠️ permanently removes untracked files

Example

# Error
$ git checkout main
error: The following untracked working tree files would be overwritten by checkout:
build/output.log
Please move or remove them before you switch branches.

# Fix
$ git stash push --include-untracked
Saved working directory and index state
$ git checkout main
Switched to branch 'main'

Alternate Scenarios

  • During merge: The same error message can appear if merging untracked files conflicts with tracked files.
  • In CI/CD pipelines: Temporary build files or artifacts left unignored can trigger this on branch switches.
  • After rebasing or pulling: Local untracked files block updates from remote branches with overlapping names.

Pitfalls & Debug

  • Symptom → Git refuses to switch branches. Fix → Use git stash push --include-untracked to temporarily store your changes.
  • Symptom → Untracked build files cause repeated warnings. Fix → Add them to .gitignore to prevent future conflicts.
  • Symptom → You accidentally deleted untracked files. Fix → They’re gone unless recovered from backup — git clean is irreversible.

Verification & Next Steps

# Check tracked vs untracked
git ls-files

# Identify overlapping files
git diff --name-only

# Confirm checkout now works
git checkout branch-name

Best Practices

  • Always review git status before changing branches.
  • Commit or stash work early — avoid large untracked changes.
  • Use .gitignore for build, log, or cache files.
  • Use git clean -nd first to preview deletions before using -fd.

Sources

Git Documentation — git checkout

Stack Overflow — untracked files overwritten by checkout

Labels

Tool/Git, OS/Cross-platform, Topic/Branch Management