Using Git rebase without creating chaos in your repo

Git rebase does not move your commits. It replays them, and every replayed commit gets a new hash. That one fact explains most of what people call rebase hell: teammates whose local branch no longer matches the remote, and force pushes that overwrite someone else's work. This post covers when to rebase, when to merge instead, how to recover a rebase that went wrong, and how to push a rebased branch without a blind force push.

Rebase buys a linear history and costs you commit hashes

Rebasing is often used to streamline a series of commits into a single, cohesive narrative. This can make your project's history much easier to follow. However, rebasing can also change commit hashes, which can be problematic for team members who have already pulled those commits.

What rebasing gives you

• Clean History: Combines multiple commits into one, making the project history easier to read.
• Linear Timeline: Ensures that the commit history is linear, which can be beneficial for project management.

What rebasing costs you

• Change of Commit Hashes: This can create headaches for collaborators, as they might need to reset their local branches.
• Complexity in Conflict Resolution: Rebasing a branch with many conflicts can be challenging and time-consuming.

Rebase vs merge: merge when there are many commits and conflicts

In cases where there are many commits and conflicts, merging might be a safer and easier option. While merging adds a new commit to your history, it preserves the commit hashes and can avoid the confusion that comes with rebasing.

# Use merge when dealing with complex conflict scenarios
git checkout main
git merge feature-branch

Recover from a rebase that went wrong

Abort with git rebase --abort before you dig deeper

If something goes wrong during a rebase, it is often best to abort and start over. This can help avoid introducing further issues.

# Abort the rebase
git rebase --abort

Let git rerere replay conflicts you have already resolved

If you find yourself fixing the same conflicts repeatedly, use git rerere to automate the resolution process.

# Enable rerere
git config --global rerere.enabled true

Use git reflog to undo a finished rebase

Once a rebase has finished, --abort is gone. The old commits still exist, and git reflog lists the HEAD positions from before the rewrite, so you can reset back to one.

Example:

1. View the reflog to find the previous state:

   git reflog

   You might see something like this:

   a1b2c3d (HEAD -> feature-branch) HEAD@{0}: rebase finished: returning to refs/heads/feature-branch
   e4f5g6h HEAD@{1}: rebase: squash commit
   i7j8k9l HEAD@{2}: checkout: moving from main to feature-branch

2. Reset to a previous state:

   git reset --hard HEAD@{2}

Four rules that keep a rebase from breaking the team

Keep the git strategy your team already agreed on

Don’t change the git strategy chosen by your organization, suddenly. If your team prefers a “squash and merge” workflow, it is best to stick with it and avoid switching to rebase.

Avoid rebasing long-lived branches

Rebasing long-lived branches can be particularly difficult due to the number of changes that have occurred. Consider whether rebasing is the best option in these scenarios.

Expect changed authorship and lost GPG signatures

When you rebase, you become a co-author on the commit, and GPG signatures might be lost. Make sure you understand these implications before proceeding.

Push with --force-with-lease, never with plain --force

You cannot rebase a branch you have already pushed and then update the remote without a force push of some kind, because the rewritten commits no longer fast-forward. Use --force-with-lease instead of --force. It only overwrites the remote branch if no one else has pushed to it since your last fetch, so you do not silently drop a teammate's commits.

Rebase your own unpushed branch as often as you like. On a shared branch, agree on the strategy first, keep the branch short, and push with --force-with-lease.

Food for thought

What is the main advantage of using git rebase?

Git rebase helps create a clean, linear project history by consolidating multiple commits into a single narrative. This makes it easier to follow the project’s development and can simplify code reviews and debugging.

When should I prefer merging over rebasing?

Merging is preferable when there are many commits with conflicts. Merging avoids changing commit hashes, making it safer and less disruptive for team members who have already pulled those commits.

How can I resolve recurring conflicts more efficiently?

Enable git rerere to record how you have resolved conflicts in the past. This can save time by automatically resolving similar conflicts in the future.

What should I do if a rebase goes wrong?

If a rebase goes wrong, abort it immediately using git rebase --abort. If you need to undo changes after a rebase, use git reflog to find the previous state and reset to it.

How do I ensure my rebase doesn’t overwrite others' changes?

After rebasing, use git push --force-with-lease instead of git push --force. This command ensures that you only overwrite the branch if no one else has pushed changes to it since your last fetch, reducing the risk of losing others' work.