Introduction

Rebasing a local branch onto remote master means replaying your local commits on top of the latest origin/master. The goal is to keep your branch current without creating a merge commit, which often produces a cleaner and easier-to-read history.

The safe sequence is: fetch the remote branch, check out your local branch, rebase onto origin/master, resolve conflicts if needed, and only then push with care. The important detail is that rebasing rewrites commit history, so the push step matters.

Fetch First, Then Rebase

Start by updating your remote-tracking refs:

git fetch origin

Then switch to the branch you want to rebase:

git checkout my-feature

Now replay your branch on top of the latest remote master:

git rebase origin/master

This tells Git to take the commits that exist on my-feature but not on origin/master, then reapply them one by one on top of the fetched remote branch.

If your repository uses main instead of master, the command would be git rebase origin/main. The mechanics are the same.

Resolve Conflicts During the Rebase

If Git finds a conflict, it pauses the rebase and tells you which files need attention. The normal loop is:

git status

Edit the conflicted files, then mark them resolved:

git add path/to/file
git rebase --continue

If the current commit should be skipped entirely, use:

git rebase --skip

If the rebase has gone in the wrong direction and you want to return to the original branch state, use:

git rebase --abort

That restores the branch to how it looked before the rebase began.

Push Carefully After History Has Changed

After a successful rebase, your local branch history is no longer identical to the remote version of that branch. If the branch already exists on the remote, a regular push may be rejected because the rewritten history no longer fast-forwards.

Use:

git push --force-with-lease origin my-feature

--force-with-lease is safer than plain --force because it refuses to overwrite remote changes you have not seen. It is the right default when you intentionally rewrote your own branch history.

That said, rebasing a shared branch that other people are already building on is still risky. Rewriting published history creates extra coordination work for everyone else.

Know When Rebase Is a Good Fit

Rebase is especially useful when:

• you want a linear history
• you are updating a personal feature branch
• you want to clean up commits before opening or updating a pull request

It is less useful when:

• the branch is heavily shared
• preserving the exact merge structure matters
• your team prefers merge commits as a historical record

Rebase is not inherently better than merge. It is a history-shaping tool, and it works best when the team agrees on when to use it.

Common Pitfalls

The biggest mistake is rebasing onto a stale local master instead of the freshly fetched origin/master. If you have not fetched first, you may still be replaying onto old history.

Another common issue is using plain git push --force after a rebase. --force-with-lease is usually the safer option.

It is also easy to rebase a branch that other people are actively using, which can force them to repair their own local histories.

Finally, do not ignore conflicts mechanically. Rebasing only improves history if the resulting code still behaves correctly after the replayed commits are resolved.

Summary

• Fetch the remote branch before rebasing.
• Rebase your local branch onto origin/master, not a stale local reference.
• Resolve conflicts with git add and git rebase --continue.
• Use git rebase --abort if you need to back out safely.
• Push rebased branches with --force-with-lease, and avoid rewriting heavily shared history.