Git Rebase vs Merge — Shared Branch Rebase Cost 6 Dev Hours

Merge and rebase both integrate changes from one branch into another. They solve the same problem in fundamentally different ways. Merge creates a merge commit that records when two branches came together. Rebase rewrites your commits so they appear to have started from the tip of the target branch.

The choice shapes your project's Git history. Merge preserves the full context of parallel development — you can see exactly what state main was in when your feature was built. Rebase produces a clean precise and git log more readable. Neither is universally better.

Common misconceptions: that rebase is always cleaner (it rewrites SHAs, which breaks shared branches), that merge always creates noise (merge commits are meaningful integration markers), and that the choice is personal preference (it is a team decision that affects debugging and collaboration).

How Git Merge Works — and What It Leaves Behind

When you run git merge, Git finds the most recent common ancestor of the two branches (called the merge base), then combines the changes from both branches into a brand-new commit. This new commit has two parents — one from each branch — which is why it's called a merge commit. It's the only commit in your repo that points backwards at two different lines of work.

This means your history is a faithful record of reality. If you and a colleague worked in parallel for a week, the graph shows that. You can run git log --graph and literally see two lanes of traffic merging into one. That's incredibly useful when you're trying to understand why a change was made in the context of what else was happening at the time.

The downside is noise. On a busy team where a dozen feature branches merge into main every day, your history fills up with merge commits that add structural information but no actual code change. Tools like git bisect and git log --oneline become harder to read. Some teams are fine with this — it's an honest record. Others find it distracting. That tension is the whole reason rebase exists.

# io.thecodeforge — Merge Feature Branch

# ─────────────────────────────────────────────────────────────
# SCENARIO: You've been building a user-authentication feature.
# A colleague just merged a critical security patch into main.
# You need those changes in your feature branch before you can continue.
# ─────────────────────────────────────────────────────────────

# Step 1 — Check your current position
git log --oneline --graph --all
# Output before merge:
# * f3a91bc (HEAD -> feature/user-auth) Add password hashing
# * 9d44e02 Add login endpoint
# | * c7b83af (main) SECURITY: sanitize SQL inputs in user queries
# | * 4e21d09 Add rate limiting middleware
# |/
# * 8b12cde Initial project scaffold

# Step 2 — Switch to your feature branch (already on it, just confirming)
git checkout feature/user-auth

# Step 3 — Merge main INTO your feature branch
# This brings the security patch into your work
git merge main
# Git opens your editor for a commit message, or auto-creates:
# "Merge branch 'main' into feature/user-auth"

# Step 4 — See what the history looks like now
git log --oneline --graph --all

How Git Rebase Works — and Why It Rewrites History

Rebase does something more radical: it replays your commits one by one on top of a new base commit. The word 'rebase' is literal — you're changing the base commit that your branch started from. The result looks as if you had branched off at the very tip of the target branch and written all your commits from there.

Here's the key thing to internalise: your original commits are not moved. Git creates brand-new commits with the same changes but different parent hashes, timestamps, and therefore different SHA-1 identifiers. The old commits still exist temporarily, but with nothing pointing to them, they'll be cleaned up by Git's garbage collector. This is not a cosmetic rename — it is a genuine rewrite.

The payoff is a perfectly linear history. When a reviewer reads your branch after a rebase, they see a clean sequence of purposeful commits with no structural noise. git log looks like a well-written changelog. git bisect works with surgical precision because every commit in the chain is meaningful. This is why many teams require rebase before merging feature branches via pull requests — you get the readability benefits of a linear history in the shared record.

# io.thecodeforge — Rebase Feature Branch onto Main

# ─────────────────────────────────────────────────────────────
# Same scenario — feature branch needs the security patch from main.
# This time we'll use rebase instead of merge.
# ─────────────────────────────────────────────────────────────

# Step 1 — Verify starting state (same branching point as before)
git log --oneline --graph --all
# * f3a91bc (HEAD -> feature/user-auth) Add password hashing
# * 9d44e02 Add login endpoint
# | * c7b83af (main) SECURITY: sanitize SQL inputs in user queries
# | * 4e21d09 Add rate limiting middleware
# |/
# * 8b12cde Initial project scaffold

# Step 2 — Make sure your working tree is clean before rebasing
git status
# Should show: nothing to commit, working tree clean

# Step 3 — Rebase the feature branch onto the tip of main
# Git will replay 9d44e02 and f3a91bc on top of c7b83af
git rebase main
# Output during rebase:
# Successfully rebased and updated refs/heads/feature/user-auth.

# Step 4 — Look at the history now
git log --oneline --graph --all

# Step 5 — If you had already pushed the old commits, force-push the rebased ones
# ONLY if nobody else has pulled your branch
git push --force-with-lease origin feature/user-auth
# --force-with-lease is safer than --force: it fails if the remote has
# commits you don't know about (someone else pushed while you were rebasing).

Warning: Never Rebase Shared Branches

The Golden Rule of rebasing is non-negotiable: never rebase a branch that another developer has pulled from. Once a commit is shared — pushed to a remote or pulled by a teammate — its SHA must never change. Rebasing a shared branch rewrites all commits, creating diverging histories that force every collaborator to hard-reset. The most common casualty is the develop branch, where a well-intentioned cleanup costs hours of team coordination.

Visual Branch History: Merge vs Rebase

Seeing the difference between merge and rebase is easier with visual diagrams. Below is a Mermaid graph showing the same initial forked history, then the result of merging, and the result of rebasing. Notice how the merge result introduces a merge commit with two parents, while the rebase result appears as a linear sequence of commits.

Before: Forked History — main has commit A, then both main and feature branches diverge. main receives commit C, feature receives commit B.

After Merge — a new merge commit D joins the two branches. Git shows both lanes of work. This is truthful parallelism but adds structural nodes.

After Rebase — feature's commit B is replayed on top of main's commit C, becoming B' with a new SHA. The history looks as if the feature was developed entirely after main's latest commit. This is easier to read but loses the fact that the feature and main commits happened concurrently.

graph TD
  subgraph "Before: Forked History"
    A[main: commit A] --> B[feature: commit B]
    A --> C[main: commit C]
  end
  subgraph "After Merge"
    D[main: commit A] --> E[feature: commit B]
    D --> F[main: commit C]
    E --> G[merge commit D]
    F --> G
  end
  subgraph "After Rebase"
    H[main: commit A] --> I[main: commit C]
    I --> J["feature: commit B' (rewritten)"]
  end

Rebasing onto Specific Branches with --onto

The git rebase --onto flag gives you fine-grained control over where your branch is rebased. Without --onto, rebasing moves the entire branch onto the new base (e.g., git rebase main rebases all commits in the current branch that are not in main onto the tip of main). With --onto, you can rebase only a subset of commits onto a completely different base.

Common use case: you started a feature branch from the wrong point — say you branched from main when you should have branched from release/v2.0. Instead of cherry-picking each commit, you can run:

git rebase --onto release/v2.0 main feature/checkout

This takes all commits on feature/checkout that are not in main and replays them on top of release/v2.0. It's a precise surgical operation.

Another scenario: you have a chain of branches (feature-A depends on feature-B). If feature-B has already been merged and you want to rebase feature-A directly onto main, you can use --onto to skip the intermediate base.

# io.thecodeforge — Rebase onto Specific Branch Using --onto

# ─────────────────────────────────────────────────────────────
# SCENARIO: You accidentally branched feature/checkout from main,
# but it should be based on release/v2.0 which has different configs.
# ─────────────────────────────────────────────────────────────

# Step 1 — Check the current state
git log --oneline --graph --all
# * e7c12d3 (feature/checkout) Add checkout validation
# * a1f84b9 Add shipping cost calculation
# | * d9e0a44 (release/v2.0) Update tax rates for EU
# | * 4e21d09 Add EU-specific checkout fields
# |/  
# * c7b83af (main) SECURITY: sanitize SQL inputs

# Step 2 — Rebase feature/checkout onto release/v2.0, skipping main
# The three-argument form: git rebase --onto <new_base> <old_base> <branch>
# old_base is main (the current base), new_base is release/v2.0
# This replays ONLY commits that are not in main (the feature commits)
git rebase --onto release/v2.0 main feature/checkout

# Step 3 — Verify the new base
git log --oneline --graph --all
# * f5c12e7 (feature/checkout) Add checkout validation
# * b4f84c1 Add shipping cost calculation
# * d9e0a44 (release/v2.0) Update tax rates for EU
# * 4e21d09 Add EU-specific checkout fields
# * c7b83af (main) SECURITY: sanitize SQL inputs

Three Real-World Workflows — Which Approach Fits Each

Knowing the mechanics is half the battle. Knowing which to reach for in a given situation is what separates a senior engineer from someone who just memorised the commands.

Workflow 1 — Keeping your feature branch up to date: Use rebase. While you're developing in isolation, nobody else is working off your branch. Rebasing onto main daily keeps your branch current without cluttering the future merge commit with a tangle of catch-up merges inside your PR. Your pull request shows exactly your work, nothing else.

Workflow 2 — Landing a feature into main via pull request: Both strategies are used in industry. Teams that value linear history use 'Squash and Rebase' in GitHub/GitLab so the entire feature lands as one clean commit. Teams that value commit granularity and want to see the feature's internal development use a regular merge commit. Know your team's convention before you hit the merge button.

Workflow 3 — Merging a long-lived shared branch (e.g. a release branch back into main): Always use merge, never rebase. Release branches are shared by the whole team. Rebasing would rewrite commits that everyone already has locally, causing a synchronisation disaster. A merge commit here is not noise — it's a meaningful event marker that says 'release 2.4.0 was integrated on this date'.

# io.thecodeforge — Interactive Rebase Cleanup Before PR

# ─────────────────────────────────────────────────────────────
# SCENARIO: You've been working on a checkout feature.
# Your commit history is messy with 'WIP' and 'fix typo' commits.
# Before raising a PR, you want to clean it up into meaningful commits.
# ─────────────────────────────────────────────────────────────

# Step 1 — See what you're working with
git log --oneline
# 8a3f21c Fix typo in promo code validator
# 7d91b4e WIP saving progress before standup
# 6c82e10 Add promo code validation logic
# 5b44a01 Add cart total calculation
# 4e30f99 (main) Set up checkout module

# Step 2 — Start interactive rebase for the last 4 commits
# The SHA here is the commit BEFORE the ones you want to edit
git rebase -i 4e30f99

# Git opens your editor showing:
# pick 5b44a01 Add cart total calculation
# pick 6c82e10 Add promo code validation logic
# pick 7d91b4e WIP saving progress before standup
# pick 8a3f21c Fix typo in promo code validator

# Step 3 — Edit the file to squash the WIP and typo fix into the promo commit
# Change 'pick' to 'squash' (or 's') for commits you want to fold in:
# pick 5b44a01 Add cart total calculation
# pick 6c82e10 Add promo code validation logic
# squash 7d91b4e WIP saving progress before standup
# squash 8a3f21c Fix typo in promo code validator

# Save and close. Git opens another editor for the combined commit message.
# Write a clean message: "Add promo code validation with edge case handling"

# Step 4 — Verify the clean result
git log --oneline

Resolving Conflicts: How Merge and Rebase Differ Under Pressure

Both commands can hit conflicts when the same lines of code were changed in both branches. But the experience of resolving those conflicts is very different — and this catches a lot of developers off guard the first time they rebase a branch with multiple commits.

With merge, you get exactly one conflict-resolution session. Git combines everything in one shot and stops if it can't. You fix the conflicts, run git add, then git merge --continue (or git commit), and you're done.

With rebase, conflicts can appear multiple times — once for each commit being replayed. If you have five commits and the second one conflicts, you'll resolve it and run git rebase --continue, then potentially hit another conflict at the fourth commit. Each resolution is isolated to the changes in that specific commit, which is actually more precise but also more repetitive. If you're not prepared for this, it feels like you've broken something when the conflict reappears.

The nuclear escape hatch is git rebase --abort, which returns your branch to exactly the state it was in before you started the rebase. There's no equivalent 'undo' once a merge commit is created — you'd need git revert or git reset, both of which are more involved.

# io.thecodeforge — Handle Rebase Conflict

# ─────────────────────────────────────────────────────────────
# SCENARIO: Rebasing a feature branch that modifies the same config
# file that main also modified — a conflict is guaranteed.
# ─────────────────────────────────────────────────────────────

# Start the rebase
git rebase main
# Auto-merging config/database.yml
# CONFLICT (content): Merge conflict in run "git rebase --continue".

# Step 1 — Open the conflicted file and look at what Git shows you
cat config/database.yml
# <<<<<<< HEAD (the tip of main, your new base)
# pool_size: 10
# timeout: 5000
# =======
# pool_size: 25
# timeout: 3000
# >>>>>>> 3c9a11f (Update database pool size for auth service)

# Step 2 — Decide what the correct value is and edit the file manually
# Edit config/database.yml to the correct final state
# Remove ALL conflict markers (<<<<<<<, =======, >>>>>>>)

# Step 3 — Stage the resolved file (do NOT git commit here)
git add config/database.yml

# Step 4 — Tell rebase to continue replaying the remaining commits
git rebase --continue
# Git may open your editor to confirm the commit message — save and close.

# Step 5 — Confirm the rebase completed cleanly
git log --oneline --graph

Recovery Procedure: Upstream Branch Was Rebasing

If a teammate rebased and force-pushed a shared branch (like develop), your local branch is now based on outdated SHAs. The typical symptom is Your branch and 'origin/develop' have diverged. The wrong instinct is to merge — that creates a duplicate set of commits and a confusing history. The correct recovery is a hard reset to the rebased remote, then cherry-pick any local commits you had made on top of the old branch.

Recovery Steps: 1. Do NOT merge. Merging creates duplicate commits from the old base and the new base. 2. Fetch the latest remote state: git fetch origin 3. Align your local branch with the rebased remote: git reset --hard origin/develop. 4. If you had local commits on top of the old develop (commits you haven't pushed or that are unique to your local), recover them by finding their SHAs in git reflog and cherry-picking them: git cherry-pick <sha>. Or, if you had a feature branch based on the old develop, you can rebase that feature branch directly onto the new origin/develop: git checkout feature/your-feature && git rebase origin/develop. 5. After recovery, communicate with your team to ensure everyone is synchronized. No one should push before all have done the hard reset.

Prevention: Branch protection rules that block force-pushes to develop and main. If a rebase of a shared branch is absolutely necessary, it must be announced with a clear timeline and a plan for everyone to reset.

# io.thecodeforge — Recover from Upstream Rebase of Shared Branch

# ─────────────────────────────────────────────────────────────
# SCENARIO: Your teammate rebased develop and force-pushed.
# You have no local work on develop, just need to get back in sync.
# ─────────────────────────────────────────────────────────────

# Step 1 — First, do NOT merge. Check the divergence:
git status
# On branch develop
# Your branch and 'origin/develop' have diverged.

# Step 2 — Fetch the rebased remote state
git fetch origin

# Step 3 — Align your local branch with the rebased remote
# WARNING: This discards any local commits on develop that are not in the remote.
# If you have unpushed commits on develop, find them first via reflog.
git reset --hard origin/develop

# ─────────────────────────────────────────────────────────────
# If you had local commits (e.g., on a feature branch based on old develop):
# ─────────────────────────────────────────────────────────────

# Step 1 — Checkout your feature branch
git checkout feature/my-feature

# Step 2 — Rebase directly onto the new origin/develop
# This replays your feature commits on top of the rebuilt develop
git rebase origin/develop

# Step 3 — Force-push your feature branch (only if you're the only one on it)
git push --force-with-lease origin feature/my-feature

Decision Guide: When to Use Merge vs Rebase

The choice between merge and rebase is not about personal preference — it's about branch type, team workflow, and what kind of history your project needs.

Use Merge When: - Integrating a shared branch (main, develop, release/*, hotfix). These branches have multiple contributors. Rebasing them would rewrite everyone's history. - Landing a large feature that has many commits and you want to preserve the internal development context. The merge commit acts as a bookmark. - Bringing a long-lived branch up to date with its base. Merge creates a single commit that records when the synchronization happened. - Working on a branch that multiple people are actively pushing to. Merge is the only safe way to integrate.

Use Rebase When: - Updating your private feature branch with changes from main. Your branch hasn't been pushed or others haven't pulled from it. - Clean up your branch's commit history before opening a pull request (interactive rebase). - You want a linear, easy-to-read git log that simplifies tools like git bisect and git log --oneline. - You're applying a sequence of patches from another branch (with --onto).

Philosophical Debate: Some teams advocate for rebase-only workflows because they produce a clean history. Others argue merge commits are essential for understanding the project's timeline. In practice, most mature teams use both: merge for shared branches and rebase for feature branches, with interactive rebase for PR preparation. The key is to establish a team convention and stick to it.

# io.thecodeforge — Decision Flow: Merge or Rebase?

# Quick personal algorithm:
# 1. Is this branch shared with other developers?
#    YES → merge
#    NO → go to 2
# 2. Is this branch long-lived (more than a week)?
#    YES → merge (preserve context)
#    NO → go to 3
# 3. Do you need to clean up commits before a PR?
#    YES → interactive rebase then push
#    NO → rebase onto target for linear history or merge if team convention