Git · troubleshooting

error: The following untracked working tree files would be overwritten by checkout

A file you have locally but never committed exists, tracked, in the branch or commits you are switching to or pulling. Git stops rather than replace it, even when the contents are identical.

Reproduced on Git 2.50.1, 23 Oct 2026. Where the text says “reproduced”, the behaviour was run on that version, not taken from documentation.

First published 23 Oct 2026

New to this? Read what is actually happening first, then come back to the steps.

On this page · 9 sections

Before you start

A terminal in the repository, and the file names the error lists.

Run this first

step 1 of 2

git status --short

Look for The files the error lists

Shows the untracked files (??) on your side.

Work out which cause you have

A few questions to narrow the list. Every answer ends in a command that confirms or rules the cause out — this cannot see your cluster, so nothing here is a certainty until you have checked.

Narrow it down

0 answered · nothing is sent anywhere

What are the listed files?

Cause space

2 of 2 still possible

You created a file that the other branch also commitsCommon
Generated files that one branch commits and yours does notOccasional

Nothing ruled out yet. Answer the question above and the branches your answer eliminates will strike through here.

Or diagnose it manually

In this order. The first command usually contains the whole answer.

Step 1
```
git status --short
```
Shows the untracked files (??) on your side.
Look for The files the error lists
Step 2
```
git ls-tree -r --name-only BRANCH -- FILE
```
Confirms the other branch tracks a file at that path.
Look for The path printed back

Every cause, and how to fix it

Ordered by how often each one turns out to be the answer.

You created a file that the other branch also commits

Common

A config file, script or README made locally, while someone else committed a file at the same path.

Confirm

git status --short -- FILE
git show BRANCH:FILE | diff - FILE

?? next to the file, then any differences from the branch's copy

Fix

Keep yours to compare later: mv FILE FILE.mine, switch or pull, then merge anything you need by hand.
Or stash it with the untracked flag: git stash push -u, switch, then git stash pop when back on your branch.
If the diff is empty or you do not need it, delete the file and switch.

git stash push -u -m before-switch
git switch BRANCH

Reproduced on Git 2.50.1: the switch then succeeded and the stash kept the local file.

Generated files that one branch commits and yours does not

Occasional

Build output, vendored dependencies or a lock file that another branch started committing, while your build created them locally.

Confirm

git clean -n -- PATH

The generated files listed as Would remove

Fix

Delete the generated files (git clean -f -- PATH after checking the -n output), switch, and rebuild.
Then agree in the team whether those files are committed or ignored, so the branches stop disagreeing.

Understanding it properly

Skip this if you are mid-incident — the working part of the page is above. Worth reading afterwards, because understanding the mechanism is what stops the next one.

In plain terms

Git only protects files it knows about by committing or stashing them. This file is not in your branch, so Git has no copy of it, but the other branch has a file at the same path. Switching would destroy your copy, so Git refuses. Move it aside, stash it, or delete it if you do not need it.

Words used on this page

Untracked file: A file on disk that is not in the last commit and not ignored; git status shows it as ??.
Ignored file: A file matched by .gitignore or .git/info/exclude. Git treats these as disposable.

What is actually happeningadvanced

Reproduced on 23 October 2026 with Git 2.50.1 and with Git 2.43.0 on Ubuntu 24.04. With an untracked config.yml that the other branch tracks, git switch and git checkout printed this error and Please move or remove them before you switch branches, then Aborting, exit 1. git merge and git pull said overwritten by merge instead. Nothing changed.

It refused even when the local file had exactly the same contents as the branch's version, so this is about Git having no record of the file, not about a difference.

When the same file was listed as ignored, git switch went ahead and replaced it with no warning. git-checkout documents this as the default; --no-overwrite-ignore turned it back into this error.

How to tell this is your problemsignals

Where	What you see
git switch or git checkout	error: The following untracked working tree files would be overwritten by checkout: FILE … Please move or remove them before you switch branches. Aborting
git pull or git merge	error: The following untracked working tree files would be overwritten by merge: FILE

How to know it is actually fixed

The switch or pull completes, and your local version is in the stash or saved under another name.

Stopping it happening again

Decide per path whether a file is committed or ignored, and keep that the same across branches.
Keep machine-local settings in files that are ignored on every branch and never committed.

Security considerations

git checkout -f, git switch -f and git clean -f delete untracked files with no copy kept. Run git clean -n first to see what would go.
Ignored files get no such protection: switching to a branch that tracks one overwrites it silently. Use --no-overwrite-ignore to make Git refuse instead.

Sources

Behaviour described here is drawn from official documentation. Where a figure could not be confirmed on an official page it is attributed in the text rather than stated as canonical.

Did this get you to an answer?

No text box on purpose — please do not paste production logs anywhere

Something wrong or out of date? Report it