Git: failed to push some refs (rejected)

You push and Git bounces it back:

! [rejected]        main -> main (non-fast-forward)
error: failed to push some refs to 'origin'
hint: Updates were rejected because the remote contains work that you do
      not have locally.

This is Git protecting shared history. The remote branch has commits that your local branch doesn't — usually a teammate pushed, or you committed from another machine. Git won't let you overwrite that work, so it rejects the push.

Step 1: Get the remote's commits

Bring the missing commits down and replay yours on top:

git pull --rebase origin main

--rebase keeps history linear: it puts the remote's commits first, then re-applies your commits after them. (A plain git pull also works but adds a merge commit.)

Step 2: Resolve conflicts if they appear

If you and the remote changed the same lines, the rebase pauses:

git status                 # shows the conflicted files
# edit the files, keep the right lines, remove the <<<< ==== >>>> markers
git add <file>
git rebase --continue

Repeat until the rebase finishes cleanly.

Step 3: Push again

Now your branch is ahead of the remote in a straight line, so the push fast-forwards:

git push origin main

The one thing not to do

Do not reach for git push --force to make the error go away. Force-pushing overwrites the remote's history and erases whatever your teammate pushed. If you truly must force (e.g. after rebasing your own feature branch), use --force-with-lease, which refuses to clobber commits you haven't seen.

The checklist

1. git pull --rebase origin <branch> — take the remote's work first.
2. Resolve any conflicts, git add, git rebase --continue.
3. git push — it fast-forwards now.
4. Never blind --force; use --force-with-lease only on your own branches.