Pointer Walk

Git Branches: Merge or Rebase

Two lines of work have to become one. Fast-forward, merge commit and rebase give the same files and three different histories.

Developer ToolsIntermediate10 min read

What a branch really is

It is easy to imagine a branch as a copy of the project in a separate folder. It is nothing like that.

In Git, every commit points back at the commit before it, its parent. That makes a chain. A branch is a label stuck on one commit. Making a commit on a branch moves the label forward to the new commit.

One more label, HEAD, marks which branch you are on.

That is all. A branch is a file containing one commit id. This is why making one is instant, and why having hundreds costs nothing. See What git commit Writes for what is underneath.

Sooner or later the work on a branch has to come back into main. There are three ways it can happen, and the differences are easiest to see as pictures.

1. Fast-forward

You branch, you commit twice, and meanwhile nobody touches main.

Fast-forward: main just catches upInteractive

$ git log

ABHEAD → main

Start. Two commits on main. Each commit points back at the one before it. A branch is nothing more than a label stuck on one commit.

Commits in the history of main
2
Commits with two parents
0
You are on
main

main has nothing of its own to combine. Git moves the label forward and is done. No new commit, no chance of a conflict.

2. A merge commit

More often, main has moved on while you worked. Each branch has commits the other lacks.

Merge commit: tie the two lines togetherInteractive

$ git log

ABHEAD → main

Start. Two commits on main. Each commit points back at the one before it. A branch is nothing more than a label stuck on one commit.

Commits in the history of main
2
Commits with two parents
0
You are on
main

Git works out the combined result and saves it as a merge commit: a commit with two parents.

bash
git switch main
git merge feature

Nothing that existed before is changed. The history records what really happened, including that two lines of work ran side by side.

3. Rebase

Rebase takes a different view: rewrite your branch so that it looks as if you had started from the latest main.

Rebase: replay your commits on top of mainInteractive

$ git log

ABHEAD → main

Start. Two commits on main. Each commit points back at the one before it. A branch is nothing more than a label stuck on one commit.

Commits in the history of main
2
Commits with two parents
0
You are on
main
bash
git switch feature
git rebase main
git switch main
git merge feature        # a fast-forward now

Git takes each of your commits in turn, works out what it changed, and applies that change on top of main. The results are new commits with new ids. They hold the same changes, but they are different objects. The old ones are left behind.

Same files, different history

Fast-forward: main just catches upInteractive
Method

$ git log

ABHEAD → main

Start. Two commits on main. Each commit points back at the one before it. A branch is nothing more than a label stuck on one commit.

Commits in the history of main
2
Commits with two parents
0
You are on
main

All three end with the same files in main. What differs is the story the history tells.

Fast-forwardMerge commitRebase
Possible whenmain has not movedAlwaysAlways
New commits madeNoneOne, with two parentsA new copy of each of your commits
Shape of historyA straight lineA fork and a joinA straight line
Existing commits changedNoNoYes, yours are replaced
Shows the work happened in parallelNot applicableYesNo

Good at

  • Merge: never rewrites anything, so it is always safe
  • Merge: keeps the true record, and one revert of the merge commit undoes the whole feature
  • Rebase: a straight history that is easy to read and to search with git bisect
  • Rebase: conflicts are dealt with one small commit at a time

Where it bites

  • Merge: a busy project ends up with a tangled graph and many merge commits
  • Rebase: replaces commits, which causes trouble if anyone else already has the old ones
  • Rebase: the same conflict can come up again for several commits in a row
  • Rebase: the rewritten commits were never tested in the form they now have

The one rule of rebase

Do not rebase commits that other people have already pulled.

Rebase makes new commits and abandons the old ones. If a teammate has built on your old commits, their work now hangs off commits that are no longer in your branch. Sorting that out is painful.

Rebasing your own branch that nobody else uses is fine, and common. A shared branch such as main is never rebased.

Conflicts

Git combines changes by itself when they touch different lines. A conflict is when both sides changed the same lines, and Git will not guess who is right.

It stops and marks the place in the file:

text
<<<<<<< HEAD
timeout = 30
=======
timeout = 60
>>>>>>> feature

The part above ======= is your current branch. The part below is what is coming in.

  1. Open the file and decide

    Keep one side, the other, or write something that combines both. Delete the three marker lines.

  2. Mark it as resolved

    git add the file.

  3. Continue

    git commit for a merge, or git rebase --continue for a rebase.

If it is going badly, git merge --abort or git rebase --abort puts everything back as it was before you started. See also Undoing Things in Git.

What teams usually do

  • Rebase your own branch onto main to pick up other people's work and keep your commits together.
  • Merge into main through a pull request, so the shared branch is never rewritten.
  • Many teams squash: the whole branch is combined into a single commit on main. The history is one commit per feature, and the small work-in-progress commits are dropped.

There is no single right answer. What matters is that a team picks one way and everyone follows it.

Key takeaways

  • A branch is a label pointing at one commit. Creating one copies nothing.
  • If main has not moved, bringing a branch in is a fast-forward: the label slides along.
  • A merge commit has two parents and joins two lines of work without changing either.
  • Rebase replays your commits on top of another branch, giving a straight history made of new commits.
  • Never rebase commits that others have already pulled.

Your progress

Check your progress

0%

  1. Read the page50% of this page

    When you have gone through the page and its animations, tick it off.

  2. Take the quiz50% of this page

    8 questions, from easy to hard. Take it as often as you like: the questions change, and only your best score counts.

Saved on this device only. See all your progress