The Error
You run git push and Git refuses:
! [rejected] main -> main (non-fast-forward)
error: failed to push some refs to 'github.com:you/project.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.It means the remote branch has commits you don't have (a teammate pushed, you edited on GitHub, or you pushed from another machine). Git won't let your push silently erase them.
🎯 Quick Fix
git pull --rebase origin main # replay your commits on top of the remote ones
# fix any conflicts, then:
git push origin mainThat's the right fix in most cases.
Why It Happens
You and the remote both started from B. The remote moved to C, you moved to D. Pushing D would require dropping C, which isn't a "fast-forward," so Git rejects it.
Option 1: Rebase (Clean History)
git fetch origin
git rebase origin/main
# if conflicts: edit files, then
git add
git rebase --continue
git push origin main Your commit D is replayed on top of C, giving a straight line: A → B → C → D′.
Option 2: Merge (Keep Both Histories)
git pull origin main # or: git pull --no-rebase
# resolve conflicts if any, commit
git push origin mainThis creates a merge commit joining C and D. Fine for shared branches and safer if you're unsure.
| Rebase | Merge | |
|---|---|---|
| History | Linear | Shows the branch and merge |
| Rewrites your local commits? | Yes (new hashes) | No |
| Good for | Your own, unpushed commits | Shared branches, beginners |
Make rebase your default for pulls (optional):
git config --global pull.rebase trueOption 3: Force Push (Only When You Mean It)
Sometimes you intentionally rewrote history, for example after rebasing or amending commits on your own feature branch. Then use:
git push --force-with-lease origin my-featuregit push --force to a shared branch like main. It deletes teammates' commits from the remote. --force-with-lease is safer: it refuses if the remote has changed since you last fetched, so you can't overwrite work you haven't seen.
Other Causes of "Rejected"
| Message | Cause | Fix |
|---|---|---|
non-fast-forward |
Remote has new commits | Pull with rebase or merge |
protected branch hook declined |
Branch protection (e.g. PRs required) | Push to a branch and open a pull request |
fetch first |
Same as non-fast-forward | git pull --rebase |
refusing to allow ... workflow scope |
Token lacks permission to edit GitHub Actions files | Use a token with the workflow scope |
| First push to a new repo with a README | Remote has an initial commit you don't | git pull --rebase origin main (or --allow-unrelated-histories once) |
Prevent It
-
git pull --rebasebefore starting work and before pushing - Work on feature branches, not directly on
main - Push small changes often
- Use pull requests for shared branches
- Prefer
--force-with-leaseover--force, always
Frequently Asked Questions
What does non-fast-forward mean in Git?
It means the remote branch contains commits that your local branch doesn't have, so your push can't simply move the branch forward. Git rejects it to avoid losing those commits. Pull and integrate the remote changes first, then push.
Should I use git pull --rebase or merge?
Rebase gives a cleaner, linear history and is ideal for your own unpushed commits. Merge preserves history exactly and is safer on shared branches. Both resolve the rejected push; many teams set pull.rebase to true for everyday work.
Is git push --force-with-lease safe?
It's much safer than --force because it refuses to overwrite the remote branch if someone else has pushed since your last fetch. Use it on your own branches after rebasing, and avoid force-pushing shared branches like main.
Conclusion
"Push rejected (non-fast-forward)" means the remote has commits you don't. Pull them in with git pull --rebase (or a merge), resolve any conflicts, and push again. Force-push only your own branches, and only with --force-with-lease.
Sources
- Git documentation: git-push
- Git documentation: git-pull (rebase option)
- GitHub Docs: Dealing with non-fast-forward errors
Last verified: 2 November 2026.
Related reads: GitHub Actions Secrets Guide · Why Anthropic Replaced Git · CI/CD Explained
I write practical guides for developers. Follow on LinkedIn or X, or invite me to speak.