What rebasing does and when to use it

Rebasing takes the commits you made on your branch and replays them on top of a different base — usually the latest version of the main branch. When you rebase instead of merge, you avoid a merge commit and keep your project history linear. This is useful when you want a clean record of what changed and when, especially before pulling your work into a shared branch.

Merge conflicts happen because Git cannot automatically decide which version of a file to keep when both branches changed the same lines. Rebasing surfaces these conflicts earlier than a merge would, which means you fix them while your changes are still fresh in your mind. The tradeoff is that rebasing rewrites your commit history — if you have already pushed your branch to a shared repository, rebasing can create problems for anyone else working on that branch.

Use rebasing on branches that only you are working on. If your branch is shared or already pushed, a merge is usually safer.

Key Takeaways

  • Rebasing replays your commits on top of the latest main branch, which keeps history linear but rewrites your commit history.
  • Start a rebase with git rebase main (or whatever branch you are rebasing onto), and Git will pause if it finds conflicts.
  • When a conflict stops the rebase, open the conflicted files, choose which version to keep, then run git add and git rebase --continue.
  • If the rebase goes wrong, git rebase --abort returns you to where you started with no changes made.
  • Only rebase branches that you alone are working on; do not rebase branches that are shared or already pushed to a repository others use.

Starting a rebase and understanding what Git shows you

Before you rebase, make sure you are on the branch you want to rebase. Run git branch to see which branch you are currently on — it will have an asterisk next to it. If you need to switch, use git checkout your-branch-name.

Next, make sure your working directory is clean. Run git status. If you have uncommitted changes, either commit them with git commit -m "your message" or stash them with git stash so Git can work cleanly. Then run git rebase main (replace main with whatever branch you are rebasing onto).

Git will start replaying your commits. If there are no conflicts, the rebase finishes silently and you are done. If there are conflicts, Git pauses and tells you which files have them. The output looks like this:

CONFLICT (content): Merge conflict in src/config.js error: could not apply abc1234... Update API endpoint Resolve all conflicts manually, then run "git rebase --continue".

This tells you the file name, which commit caused the problem, and what to do next.

Finding and reading conflict markers in your files

Open the conflicted file in your editor. Git marks the conflict with special lines that look like this:

<<<<<<< HEAD const apiUrl = "https://api.example.com/v2"; ======= const apiUrl = "https://api.example.com/v1"; >>>>>>> abc1234 Update API endpoint

The section between <<<<<<< and ======= is what was already on the main branch (the base you are rebasing onto). The section between ======= and >>>>>>> is what your commit tried to add. The label after >>>>>>> is the commit hash and message from your branch.

You need to decide which version to keep, or write a new version that combines both. Delete the conflict markers and the lines you do not want, leaving only the code that should be there. In this example, if the v2 endpoint is correct, delete the ======= line, the v1 line, and all the >>>>>>> line, leaving only the v2 version.

Completing the rebase after you fix conflicts

After you have edited the file and removed all conflict markers, save it. Then run git add src/config.js (use the actual file name). This tells Git that you have resolved the conflict in that file.

If multiple files had conflicts, repeat the process for each one — open it, fix the markers, save, and run git add on each. Then run git rebase --continue. Git will replay the next commit. If that one also has conflicts, you will fix those the same way. Keep going until all commits are replayed and Git returns you to the command prompt.

If you realize mid-rebase that you made a mistake, you can always run git rebase --abort. This cancels the entire rebase and returns your branch to exactly how it was before you started. You lose no work — your commits are still there, just not rebased yet.

Pushing your rebased branch and avoiding problems with shared branches

Once the rebase is complete, your branch is ready to push. However, because rebasing rewrites history, you cannot use a normal git push. Run git push --force-with-lease origin your-branch-name instead. The --force-with-lease flag is safer than --force because it will refuse to push if someone else has added commits to the remote branch since you last pulled.

This is why rebasing is only safe on branches that only you are working on. If a coworker is also pushing to the same branch, a force push will overwrite their work. If your branch is shared, use git merge instead — it creates a merge commit, but it does not rewrite history and is safe for shared branches.

If you have already pushed your branch before rebasing and you are not sure whether anyone else is using it, ask your team before force-pushing. In many teams, the convention is to rebase before opening a pull request, then push normally once the request is open and reviewed.

Common mistakes and how to fix them

The most common mistake is rebasing a branch that is shared or already pushed. If you have done this and force-pushed, and a coworker has also pushed commits, their commits are now orphaned and they will have to recover them manually. The best prevention is to only rebase branches you own, and to ask before rebasing anything shared.

Another common mistake is editing the wrong file during a conflict. If you fix the conflict in the wrong place or delete code you meant to keep, run git rebase --abort immediately. Your branch returns to its original state with no damage. You can then start the rebase again and be more careful.

If you have already run git rebase --continue after fixing a conflict wrong, you can still undo it. Run git reflog to see a list of recent states, find the one before the rebase started (it will say something like "rebase: starting"), and run git reset --hard followed by that state's hash. This is a last resort and should only be used if you are certain the rebase went wrong.

Frequently Asked Questions

What is the difference between rebasing and merging?

Merging creates a new commit that combines two branches and keeps both histories intact. Rebasing replays your commits on top of another branch, creating a linear history but rewriting your commit history. Merge is safer for shared branches; rebase is cleaner for personal branches before a pull request.

Can I rebase if I have already pushed my branch?

You can, but only if you are the only person working on that branch. After rebasing, you must use git push --force-with-lease to push. If anyone else has pushed to the same branch, do not rebase — use merge instead to avoid overwriting their work.

What does "git rebase --abort" do?

It cancels the rebase and returns your branch to exactly how it was before you started. All your commits remain, nothing is lost, and you can try again or use a different approach.

Do I have to resolve all conflicts at once?

No. Git pauses at each commit that has conflicts. You fix that commit's conflicts, run git add and git rebase --continue, and Git moves to the next one. You resolve them one commit at a time as you go.

What if the same file has conflicts in multiple commits?

You will fix it multiple times — once for each commit that changed it. This is normal. Open the file, resolve the markers for that commit, save, run git add, and continue. When you reach the next commit that touches the same file, you will fix it again if there are new conflicts.