non-fast-forward
This error occurs when you try to push commits that do not build directly on top of the remote branch's head commit.
Usually happens because:
- ☑ Tip of your current local branch is behind the remote tracking head
- ☑ You amended or rebased commits that were already pushed
- ☑ Remote branch was modified directly in web interface
🔍 Quick Checklist:
What is non-fast-forward?
A non-fast-forward error happens when the history of your local branch has diverged from the remote branch. In a fast-forward push, Git can simply move the remote pointer forward in time because your commits are a direct extension of the remote's history. If the remote has new commits that are missing from your local history, Git rejects the push with a 'non-fast-forward' warning to protect the remote history from being rewritten.
Common Causes
- Diverged commits on remote: Another user pushed changes to the same branch since your last fetch/pull operation.
- Amending local history: Running 'git commit --amend' or rebasing commits that have already been pushed to the remote repository.
- Force merges on remote: Pull requests merged on the remote repository (e.g. Squash and Merge) creating a different commit history.
| Cause | Frequency |
|---|---|
| New commits pushed by others concurrently | ⭐⭐⭐⭐⭐ |
| Amending commits already pushed to origin | ⭐⭐⭐⭐ |
| Remote squash merge creating history divergence | ⭐⭐⭐ |
Common Mistakes
- Running `git push -f` immediately after receiving the rejection message, which risks deleting changes pushed by team members.
- Attempting to pull changes using merge commits when the team policy mandates clean linear rebase histories.
How to Fix
Git Operations & Verification
Output branch commit graph splits to see where your local history diverged from the remote host.
$ git log --oneline --graph --all
* a1b2c3d (HEAD -> feature-xyz) Local changes
| * e5f6g7h (origin/feature-xyz) Remote updates pushed by teammate
|/
* 9z8y7x6 Base common commitPlatform Specific Fixes
Visualizing local vs remote tracking heads on Linux terminals.
git show-branchBest Practices
- Run `git fetch` before coding to make sure you are working off the latest version of the code.
- Do not amend or rewrite commit messages for commits that have already been pushed to a public remote branch.
Frequently Asked Questions (FAQ)
Q: What is a non-fast-forward push?
It is a push that would overwrite remote commits because your local branch does not have the latest remote commits inside its history.
Q: How does Git perform a fast-forward merge?
When the target branch has no new commits, Git just moves the branch pointer forward to the commit on the source branch without creating a merge commit.
Q: Is it bad to force-push?
Yes, if other developers are working on the same branch, force-pushing will overwrite their remote work and break their local tracking history. Avoid force-pushing to shared branches like 'main' or 'develop'.
Q: How do I prevent non-fast-forward errors?
Pull remote updates frequently using 'git pull' or 'git fetch' before making changes to shared code paths.