git push Rejected: How to Fix 'Remote Repository Contains Commits Not Present Locally'

One of the most common Git errors during a push is that git push gets rejected because the remote repository already contains commits that are missing from your local branch. In practice, this is usually a non-fast-forward push failure.

I ran into this while updating the bobobk-hugo theme used by this blog. The error looked like this:

(base) ➜  bobobk-hugo git:(master) git push origin
Username for 'https://github.com': tengbozhang
Password for 'https://tengbozhang@github.com': 
To https://github.com/tengbozhang/bobobk-hugo.git
 ! [rejected]        master -> master (fetch first)
error: failed to push some refs to 'https://github.com/tengbozhang/bobobk-hugo.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.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

This message means the remote branch has moved ahead of your local branch. Git refuses the push because it does not want to overwrite commits that exist remotely but are missing locally.

Why this happens

The most common causes are:

1. You edited files directly on GitHub and never pulled those changes locally
2. Another person pushed commits to the same branch
3. You made commits on another machine, and the current machine is behind

As soon as the remote and local branch histories diverge, a direct push can fail with this message.

The most common fix

In day-to-day use, the usual fix is to bring in the remote updates first, place your local work on top of them, and then push again. A common command sequence is:

git pull --rebase origin master
git add .
git commit -m "your message"
git push origin master

If your local work is already committed, an even more typical flow is:

git status
git add .
git commit -m "your message"
git pull --rebase origin master
git push origin master

The reason to prefer git pull --rebase over plain git pull is that it usually keeps the history cleaner and avoids creating an unnecessary merge commit.

What if rebase reports conflicts?

If both the remote branch and your local branch changed the same lines, rebase may stop with conflicts. In that case, the flow is usually:

# Check which files are conflicted
git status

# After resolving the conflict manually
git add conflicted_file
git rebase --continue

If you want to cancel the rebase instead:

git rebase --abort

Why you should not default to force push

Some people respond to this error by running:

git push --force

That can work on a private temporary branch, but on shared branches such as master or main, it may overwrite other people’s commits. Unless you fully understand the consequences, --force should not be the default answer to this error.

A safer way to inspect the situation first

If you want to confirm what changed before pulling, use:

git fetch origin
git status
git log --oneline --graph --decorate --all -20

That gives you a quick view of how your local branch differs from the remote branch before you choose between rebase, merge, or conflict resolution.

Summary

When git push is rejected because the remote repository contains commits that do not exist locally, the root issue is usually that the remote branch is ahead and the push is no longer a fast-forward update.

The practical fix is usually: sync the remote branch first, use git pull --rebase to place your local commits on top of the latest remote history, and then push again. Once you understand that workflow, this Git error becomes much easier to handle.