Git Merge vs Rebase
Tags: git, merge, rebase, beginners
Published: 2021-07-01 13:22:23

**An FAQ that explains and answers when to use which and why.**

There's a common discussion among developers about how teams should use [Git](https://git-scm.com/) to make sure everyone is always up-to-date with the latest changes in the `main` branch. The typical situation this question arises is when someone worked on a new branch and then once the work is done and ready to be merged, the main branch had changes in the meantime in a way that the work branch is outdated and now has **merge conflicts**.

Obviously, they need to be resolved before the work branch can be merged. But the question is: *How* should this situation be resolved? Should we _**merge**_ the `main` branch into the work branch? Or should we _**rebase**_ the work branch onto the latest `main` branch?

In my opinion, there's only one correct answer to this question. From my experience, the main reason why so many discussions arise around this topic is that there's a lot of misunderstandings out there about how `merge` and `rebase` differ from each other in this context and a general lack of understanding, what a `rebase` even is.

So I created an FAQ for my team which tries to clarify things. Let me share:

### What is a `merge`?

A commit, that combines all changes of a different branch into the current.

### What is a `rebase`?

Re-comitting all commits of the current branch onto a different base commit.

### What are the main differences between `merge` and `rebase`?

1. `merge` executes only **one** new commit. `rebase` typically executes **multiple** (number of commits in current branch).
2. `merge` produces a **new** generated commit (the so called merge-commit). `rebase` only moves **existing** commits.

### In which situations should we use a `merge`?

Use `merge` whenever you want to add changes of a branched out branch **back** into the base branch.

Typically, you do this by clicking the "Merge" button on Pull/Merge Requests, e.g. on GitHub.

### In which situations should we use a `rebase`?

Use `rebase` whenever you want to add **changes of a base branch** back to a branched out branch.

Typically, you do this in `work` branches whenever there's a change in the `main` branch.

### Why not use `merge` to merge changes from the base branch into a work branch?

1. The git history will include many **unnecessary merge commits**. If multiple merges were needed in a work branch, then the work branch might even hold more merge commits than actual commits!
2. This creates a loop which **destroys the mental model that Git was designed by** which causes troubles in any visualization of the Git history.

    Imagine there's a river (e.g. the "Nile"). Water is flowing in one direction (direction of time in Git history). Now and then, imagine there's a branch to that river and suppose most of those branches merge back into the river. That's what the flow of a river might look like naturally. It makes sense.

    But then imagine there's a small branch of that river. Then, for some reason, **the river merges into the branch** and the branch continues from there. The river has now technically disappeared, it's now in the branch. But then, somehow magically, that branch is merged back into the river. Which river you ask? I don't know. The river should actually be in the branch now, but somehow it still continues to exist and I can merge the branch back into the river. So, the river is in the river. Kind of doesn't make sense.

    This is exactly what happens when you `merge` the base branch into a `work` branch and then when the `work` branch is done, you merge that back into the base branch again. The mental model is broken. And because of that, you end up with a branch visualization that's not very helpful.

### Example Git History when using `merge`:

[![Example Git History when using `merge`][1]][1]

Note the many commits starting with `Merge branch 'main' into ...` (marked with yellow boxes). They don't even exist if you rebase (there, you will only have pull request merge commits). Also note the many visual branch merge loops (`main` into `work` into `main`).

### Example Git History when using `rebase`:

[![Example Git History when using `rebase`][2]][2]

Much cleaner Git history with much less merge commits and no cluttered visual branch merge loops whatsoever.

### Are there any downsides / pitfalls with `rebase`?

Yes:

1. Because a `rebase` moves commits (technically re-executes them), the commit date of all moved commits will be the time of the rebase and the **git history loses the initial commit time**. So, if the exact date of a commit is needed for some reason, then `merge` is the better option. But typically, a clean git history is much more useful than exact commit dates.
2. If the rebased branch has multiple commits that change the same line and that line was also changed in the base branch, you might need to solve merge conflicts for that same line multiple times, which you never need to do when merging. So, on average, there's more merge conflicts to solve.

### Tips to reduce merge conflicts when using `rebase`:

1. **Rebase often**. I typically recommend doing it at least once a day.
2. Try to **squash changes** on the same line into one commit as much as possible.


  [1]: https://i.stack.imgur.com/Oqqmm.png
  [2]: https://i.stack.imgur.com/0ZVla.png

I hope this FAQ helps some teams out there. Like ❤️ it if you liked it! 😉

_This article was written **by [Cihat Gündüz](https://twitter.com/Jeehut)**