Fixing Git Error: Untracked working tree files would be overwritten by checkout

Why Git Blocks Your Branch SwitchYou are ready to switch branches to review a PR or pull the latest updates. You run git checkout main, but instead of a success message, Git stops you cold with a technical block. It looks like this:

error: The following untracked working tree files would be overwritten by checkout:
    config/settings.local.php
    dist/bundle.js
Please move or remove them before you switch branches.
Aborting

This error is a safety feature. Git is protecting your data. It happens because you have files in your folder that Git isn't tracking yet. However, the branch you are moving to does track those same file paths. If Git allowed the switch, it would overwrite your local files with the repository's versions. Your local work would be deleted instantly.

Identify the Culprits FirstBefore you run any commands that might delete data, check what these files actually are. Are they 50MB build artifacts like dist/bundle.js, or are they 1KB configuration files you spent an hour tweaking? Run git status to see the full list.

git status

If the files listed in the error message appear under "Untracked files," choose one of the following four paths based on how much you value that data.

Solution 1: The Manual Backup (Safest)Move the files if they contain sensitive API keys or code you haven't committed. This is the best approach when you aren't 100% sure if the files are disposable. It only takes a few seconds to be safe.

# Create a temporary backup folder outside your repo
mkdir ../git_backup

# Move the conflicting files
mv config/settings.local.php ../git_backup/

# Now switch branches
git checkout destination-branch

After switching, you can manually compare your backed-up version with the one Git just pulled down.

Solution 2: Using Git Clean (Best for Build Junk)Sometimes the conflict comes from build artifacts, log files, or node_modules debris. If you don't care about these files, use git clean to wipe them out. Note: This action is permanent and cannot be undone.

Always perform a "dry run" first to see what will be deleted:

git clean -n

If the list looks safe, run the command with the force and directory flags:

# -f for force, -d to remove directories
git clean -fd

Once the working tree is clear, your git checkout will work immediately.

Solution 3: The Forceful SwitchUse the force flag if you want to switch branches right now and don't care about losing those untracked files. This tells Git to prioritize the repository's version over your local files.

git checkout -f destination-branch

Warning: Git will overwrite your local untracked files. Since Git never tracked these files, there is no history to recover them from if you change your mind.

Solution 4: Track and Stash (The Professional Way)Perhaps you realized these files should have been part of the repository all along. In this case, track them, hide them temporarily in the stash, and then move branches. This keeps your work history clean.

# 1. Stage the files
git add config/settings.local.php

# 2. Stash them safely
git stash

# 3. Switch branches
git checkout destination-branch

# 4. (Optional) Bring your changes back
git stash pop

If you use stash pop and the target branch has different content in those files, Git will trigger a standard merge conflict. This is much safer than a hard overwrite because you can choose which lines to keep.

How to Prevent This in the Future- Audit your .gitignore: This error usually stems from files that shouldn't be tracked, like dist/ or .env. Ensure these are listed in your .gitignore file so Git ignores them entirely.- Keep a clean house: Run git status frequently. The fewer untracked files you have sitting around, the less likely you are to hit path collisions.- Coordinate with your team: If multiple developers are adding new files to the same paths in different branches, coordinate on a standard folder structure to avoid these conflicts.