Git: push rejected — Updates were rejected because the remote contains work

Hi, it's BlueByte. You run git push and, instead of uploading your commits, Git stops with ! [rejected] main -> main (fetch first) and a paragraph that says the remote contains work you don't have. Nothing is broken and no commits are lost — Git is refusing to overwrite history it can see and you can't. The symptom is a push that ends in Updates were rejected with either (fetch first) or (non-fast-forward) in the reject line. We'll walk through what those two variants mean, why the push was refused, how to bring the two histories together safely, and how to keep it from happening.

What "(fetch first)" and "(non-fast-forward)" are telling you

The full rejection reads like this:

! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'github.com:acme/app.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.

Git only accepts a push when your branch is a straight continuation of the remote branch — a fast-forward. When the remote has moved on, your commit is no longer a direct descendant of its tip, so Git refuses rather than throw away the remote's commits. The two hint words tell you which case you're in: (fetch first) means your local branch simply hasn't seen the remote's new commits yet, and (non-fast-forward) means the two histories have actually diverged — both sides have commits the other doesn't.

The two situations that produce a rejected push

A non-fast-forward reject comes from one of these:

• Someone pushed after you last synced. A teammate or a CI job added commits to the same branch. Your history is behind, not wrong — you just need to catch up.
• You rewrote your local history. A git rebase, git commit --amend, or git reset changed commits you'd already pushed, so your branch and the remote's now disagree about the past.

The first is the common one and has a clean fix. The second needs care, because the safe fix and the dangerous one look almost identical.

See how far the histories have diverged before you act

Don't force anything yet — first fetch the remote state and measure the gap:

git fetch
git status

Your branch and 'origin/main' have diverged,
and have 1 and 2 different commits each, respectively.

That line is the whole diagnosis: you have 1 commit the remote lacks, and it has 2 you lack. To see them side by side:

git log --oneline --graph --left-right HEAD...origin/main

Commits marked < are yours; > are the remote's. If every commit is > and none is <, you're simply behind — a plain git pull will fast-forward. If both appear, the branches diverged and you'll create a merge or a rebase.

The normal fix: bring the remote work in, then push

For the everyday case — someone pushed ahead of you — pull their commits, replay yours on top, and push:

git pull --rebase
git push

Successfully rebased and updated refs/heads/main.
...
To github.com:acme/app.git
   3f2a1b0..9c8d7e6  main -> main

git pull --rebase fetches the remote commits and re-applies yours after them, so history stays linear and the push now fast-forwards. Plain git pull (a merge) works too, but leaves a merge commit. If the rebase reports a conflict, resolve the files, git add them, and run git rebase --continue.

When you rewrote history on purpose: --force-with-lease, never --force

If the divergence is because you intended to rewrite your own pushed commits — squashing a messy branch before review, say — pulling them back would undo your cleanup. Here you overwrite the remote, but do it with a safety net:

git push --force-with-lease

--force-with-lease only overwrites the remote if it still points where you last saw it — so if a teammate pushed in the meantime, the push fails instead of deleting their commit. Plain git push --force skips that check and can silently erase work someone else pushed; reach for --force-with-lease every time, and never force a shared branch like main without agreement.

A real case: a teammate pushed while you were working

You finish a fix, commit it, and git push is rejected with (fetch first) and Updates were rejected because the remote contains work that you do not have. You run git fetch and git status, which reports the branch diverged by 1 and 1. Since you didn't rewrite anything, this is the normal case: you run git pull --rebase, Git replays your one commit on top of your teammate's, and git push succeeds — the reject line is gone and both commits are on the remote, in order.

Confirm the push actually landed

Check that local and remote agree:

git status

Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean

up to date with 'origin/main' means the push fast-forwarded cleanly. git log --oneline -3 should show your commit at the tip alongside the remote's, with no (fetch first) on the next push.

Keep rejected pushes from surprising you

Fetch before you start work and again before you push, so you rarely sit behind the remote. Set git config --global pull.rebase true so git pull rebases by default and keeps history linear instead of littering merge commits. On shared branches, prefer a pull request over pushing directly, and if you must rewrite history, always use --force-with-lease so you can't clobber a colleague. Small, frequent pushes diverge less than one big push after a day of work.

How this differs from a protected-branch or "src refspec" rejection

A non-fast-forward reject is about history shape — your branch isn't a descendant of the remote's, and fetching fixes it. Two other rejections look similar but aren't: protected branch hook declined or GH006 means the server policy forbids the push regardless of history — you need a pull request, and no amount of pulling helps. And error: src refspec main does not match any means the branch doesn't exist locally at all — usually a typo or an empty repo with nothing committed yet. If the message names a hook or a refspec rather than "remote contains work," it isn't a non-fast-forward and git pull won't fix it.