This Git error occurs when you try to switch branches, but untracked files in your working directory would be overwritten by files from the target branch. Git prevents the checkout to avoid accidental data loss.
The "untracked working tree files would be overwritten by checkout" error is a safety mechanism in Git that protects you from losing work. When you attempt to switch branches using `git checkout` or `git switch`, Git compares the files in your current working directory against the files that exist in the target branch. If the target branch contains tracked files with the same names as your untracked local files, Git refuses to proceed because checking out would overwrite your local files. This commonly happens when: - You created new files locally that also exist in the branch you're switching to - Someone else added files to a branch that match files in your .gitignore - You pulled a .gitignore update that now ignores files that were previously tracked - You're working on generated files (like build outputs) that are tracked in another branch The key point is that these are "untracked" files - files that Git is not currently managing in your branch. Since Git doesn't have any record of their original contents, it cannot safely overwrite or merge them.
First, examine which files Git is complaining about:
# The error message will show something like:
# error: The following untracked working tree files would be overwritten by checkout:
# path/to/file1.txt
# path/to/file2.js
# Check the status of your working directory
git statusDecide if you need to keep these files or if they can be safely removed or replaced.
Use git stash to temporarily save your untracked files:
# Stash including untracked files
git stash push --include-untracked -m "Saving untracked files before checkout"
# Now checkout should work
git checkout <target-branch>
# Later, if you want to restore the files on this branch
git checkout <original-branch>
git stash popThis is the safest approach as it preserves your work while allowing you to switch branches.
If you want to keep the files but stash isn't suitable, manually back them up:
# Create a backup directory
mkdir -p ~/git-backup
# Copy the conflicting files (adjust paths based on error message)
cp path/to/file1.txt ~/git-backup/
cp path/to/file2.js ~/git-backup/
# Remove the files from working directory
rm path/to/file1.txt
rm path/to/file2.js
# Now checkout should work
git checkout <target-branch>If the files are generated or you don't need them, remove them with git clean:
# First, do a dry run to see what would be deleted
git clean -n -d
# If you're sure you want to delete these files
git clean -f -d
# Or delete specific files manually
rm path/to/file1.txt
rm path/to/file2.js
# Now checkout should work
git checkout <target-branch>Warning: git clean -f permanently deletes files. Use the dry run (-n) first!
If you're certain you want the target branch's version of these files:
# Force checkout - WARNING: this will overwrite your local files
git checkout -f <target-branch>Warning: This will permanently overwrite your untracked files with the versions from the target branch. Only use this if you're certain you don't need your local copies.
If these are generated files that shouldn't be tracked, add them to .gitignore:
# Add to .gitignore
echo "path/to/generated-file.txt" >> .gitignore
echo "build/" >> .gitignore
# Commit the .gitignore update
git add .gitignore
git commit -m "Add generated files to .gitignore"This prevents the same conflict from happening again in the future.
### Understanding Tracked vs Untracked Files
In Git, files exist in three states:
- Tracked: Files that Git knows about (committed or staged)
- Untracked: Files in your working directory that Git is not managing
- Ignored: Files matched by patterns in .gitignore (a special kind of untracked)
This error specifically involves untracked files that would collide with tracked files in another branch.
### The Merge Variant of This Error
A similar error occurs during git pull or git merge:
error: The following untracked working tree files would be overwritten by mergeThe solutions are the same - stash, backup, or remove the conflicting untracked files.
### Using git stash with Specific Files
If you only want to stash specific files:
# Stash specific untracked files
git stash push --include-untracked -- path/to/file1.txt path/to/file2.js### Worktrees as an Alternative
If you frequently need to work on multiple branches with conflicting untracked files, consider using Git worktrees:
# Create a new worktree for the other branch
git worktree add ../my-repo-other-branch other-branch
# Now you have two directories, each on a different branch### CI/CD Considerations
In CI/CD pipelines, this error often occurs because:
- Build artifacts from previous runs weren't cleaned up
- The pipeline doesn't start with a clean checkout
Solutions:
- Use git clean -fdx at the start of pipelines
- Configure your CI to use fresh clones
- Add build directories to .gitignore
warning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server