Introduction

rejected master -> master (non-fast-forward) means the remote branch has commits that your local branch does not contain. Git refuses the push because accepting it would overwrite remote history instead of moving the remote pointer forward safely.

What a Fast-Forward Push Means

A fast-forward push is possible only when your local branch is a direct descendant of the remote branch. In that situation, Git can move the remote reference from the old commit to your newer commit without losing anything.

A non-fast-forward rejection means the histories diverged. That usually happens because:

• someone else pushed to the branch first
• you rebased or amended locally
• you are pushing from an outdated clone

Inspect the Branch State First

Do not guess. Fetch the latest remote state and inspect the graph.

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

This quickly shows whether the remote has one or more commits you need to integrate.

Usual Fix: Rebase or Merge the Remote Changes

If you want a clean linear history, rebase your work onto the updated remote branch.

git fetch origin
git rebase origin/master

Resolve any conflicts, then continue:

git add <resolved-files>
git rebase --continue

After the rebase succeeds, push again:

git push origin master

If your team prefers merge commits, merge instead of rebasing:

git fetch origin
git merge origin/master
git push origin master

Both approaches are valid. The right one depends on your branch policy.

When --force-with-lease Is Appropriate

If you intentionally rewrote your local history, such as after an interactive rebase, a normal push may still fail even after fetching. In that case, you may need to replace the remote history.

The safer force option is:

git push --force-with-lease origin master

--force-with-lease checks that the remote branch still points to the commit you expect before overwriting it. That makes it much safer than raw --force.

Use it only when rewriting remote history is actually acceptable for that branch. On shared master or main, many teams prohibit it entirely.

Typical Team Workflow to Avoid the Error

The easiest prevention strategy is:

1. fetch or pull before starting new work on a shared branch
2. do development on feature branches, not directly on master
3. merge through pull requests
4. keep the shared branch protected from history rewrites

When teams work directly on the release branch without frequent sync, non-fast-forward rejections become normal and disruptive.

Example Recovery Scenario

Suppose your local master has commit C, but origin/master moved from A to B because a teammate pushed. Your push is rejected because Git would have to drop B to place C directly on the remote.

The correct fix is to integrate B first, producing either a rebased C' on top of B or a merge commit that combines both histories. After that, the push becomes a normal fast-forward update again.

Common Pitfalls

The biggest mistake is reaching for git push --force immediately on a shared branch. That can erase teammates' work.

Another mistake is running git pull without understanding whether it merges or rebases in your configuration. If you care about history shape, be explicit.

People also often resolve the rejection locally but forget to inspect what changed on the remote. The remote commits may include schema changes, generated files, or deployment updates that deserve review before integration.

Finally, do not treat master as a scratch branch. Protected branches work best when day-to-day development happens elsewhere.

Summary

• A non-fast-forward rejection means the remote branch contains commits your local branch does not have.
• Fetch first and inspect the history before trying random commands.
• Rebase or merge the remote branch into your local work, then push again.
• Use --force-with-lease only when history rewrite is intentional and allowed.
• Feature-branch workflows reduce the frequency of this error on shared branches.