🌿
Git Error
Git Error: failed to push some refs (non-fast-forward)
The remote branch has commits your local branch doesn't have — Git refuses to push until you incorporate them first.
What This Error Means
This means the remote branch has progressed with commits since you last pulled — someone else pushed, or you pushed from another machine — and your local branch is now behind. Git refuses a "non-fast-forward" push by default to prevent silently overwriting those remote commits.
Why It Occurs
Someone else (or you, from another machine/session) pushed commits to the same branch after your local branch's last pull, so your local history and the remote have diverged.
Symptoms
- ⚠ Appears on `git push`, specifically saying "Updates were rejected because the remote contains work that you do not have locally"
Common Causes
- • A collaborator pushed to the same branch since your last pull
- • You pushed from a different machine/session and forgot to pull those changes locally first
How to Fix It
- Pull the remote changes first: `git pull origin your-branch` — this fetches and merges the remote commits into your local branch
- Resolve any merge conflicts that arise from the pull, if the same lines were changed in both histories
- Push again: `git push origin your-branch` — this should now succeed as a fast-forward
- Alternative: `git pull --rebase` replays your local commits on top of the remote ones instead of creating a merge commit, producing cleaner history — use this if your team prefers rebase workflows
- Never use `git push --force` to bypass this on a shared branch unless you are certain no one else's work will be destroyed — force-pushing overwrites the remote history entirely
| Command | Purpose |
|---|---|
| git pull origin your-branch | Fetch and merge remote changes before pushing |
| git pull --rebase origin your-branch | Alternative: replay local commits on top of remote history |
Advertisement
Verification
- ✓ `git push` completes without rejection
- ✓ `git log` shows both your commits and the previously-remote commits present
Prevention
- → Pull before starting new work each session, especially on shared branches
- → Communicate with collaborators about who's pushing to a shared branch and when