TL;DR
Git is refusing to pull because you have uncommitted changes in files the incoming commit also touches. Three ways out:
# Option A — stash your changes, pull, then restore
git stash
git pull
git stash pop
# Option B — discard your changes entirely
git checkout -- path/to/file
git pull
# Option C — commit first, then pull
git add path/to/file
git commit -m "WIP: save local changes"
git pull
What's Actually Happening
Running git pull triggers a merge under the hood. Git compares what's in the remote branch against your local branch — and if a file you've edited locally was also changed in the incoming commits, Git stops cold:
error: Your local changes to the following files would be overwritten by merge:
src/config.js
README.md
Please commit your changes or stash them before you merge.
Aborting
This is intentional. Git won't silently blow away your work. Your edits live in the working tree (or the index if you've staged them) but haven't been committed yet, so there's nowhere safe to put them during the merge.
Fix Approaches
Option A: Stash (Recommended — keeps your changes)
Best choice when you want your local edits back after pulling — say you have debug logging or a local API key you're not ready to commit.
# 1. Stash all tracked modified files
git stash
# 2. Pull the latest changes
git pull
# 3. Reapply your stashed changes
git stash pop
If stash pop hits a conflict, Git marks the clashing lines with <<<<<<< markers. Fix them manually, then run:
git add src/config.js
git stash drop # clear the stash entry once resolved
Need to stash just one file with a meaningful label? Use:
git stash push -m "WIP: local config tweaks" src/config.js
Run git stash list anytime to see everything currently stashed.
Option B: Discard Local Changes (Destructive — changes are gone)
Only go this route when the local edits genuinely don't matter — like if you accidentally touched a file while poking around.
# Discard changes on specific files
git checkout -- src/config.js README.md
# Or nuke ALL uncommitted changes in the working tree
git restore .
# Then pull normally
git pull
Warning: Both git checkout -- <file> and git restore are permanent for uncommitted changes. No undo, no recycle bin.
Option C: Commit Your Changes First
When your edits are real work that belongs in history, just commit before pulling.
git add src/config.js README.md
git commit -m "Update config and docs"
git pull
The pull might still produce a merge conflict if both you and a teammate edited the same lines. That's fine — Git will pause and walk you through the normal conflict resolution flow.
Option D: Force Pull (Nuclear — overwrites everything)
Reserve this for throwaway branches or when you're absolutely certain you want the remote version, full stop.
git fetch origin
git reset --hard origin/main
This hard-resets your branch to match the remote exactly. Uncommitted changes vanish. Commits you made locally but never pushed? Also gone. Use with care.
Which Option Should You Use?
Pick based on what you actually want to happen to those local changes:
- Stash — you want them back after the pull (temporary debug logs, local env tweaks, experiments).
- Discard — they were accidental or irrelevant and you're happy to lose them.
- Commit — they're real work that should live in the project's history.
- Reset --hard — your local branch is a mess and you just want it to mirror the remote, no questions asked.
When Stash Pop Conflicts After Pull
Sometimes the pull lands changes on the exact same lines as your stash. Git tells you immediately:
$ git stash pop
Auto-merging src/config.js
CONFLICT (content): Merge conflict in src/config.js
The stash entry is kept in case you need it again.
Open src/config.js, find the <<<<<<< markers, and pick the right version. Then clean up:
git add src/config.js
git stash drop # drop the stash entry now that it's fully resolved
Verification
After applying your fix, confirm everything landed correctly:
# Should show your branch is up to date
git status
# Check that the latest remote commits are now in your local history
git log --oneline -5
# If you used stash pop, verify your changes came back
git diff HEAD
A clean git status showing "Your branch is up to date with 'origin/main'" means you're good.
Stop This From Happening Again
- Commit small and often. A branch with frequent small commits almost never hits this error.
- Try
git pull --rebase. It replays your commits on top of the remote instead of merging — cleaner for linear histories. It still requires a clean working tree, but the result is tidier. - Add a sync alias for the stash-pull-pop dance:
git config --global alias.sync '!git stash && git pull && git stash pop'. Thengit synchandles it in one shot.