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 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
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
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:
A commit, that combines all changes of a different branch into the current.
Re-comitting all commits of the current branch onto a different base commit.
mergeexecutes only one new commit.
rebasetypically executes multiple (number of commits in current branch).
mergeproduces a new generated commit (the so called merge-commit).
rebaseonly moves existing commits.
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.
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
- 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!
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
mergethe base branch into a
workbranch and then when the
workbranch 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.
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 (
Much cleaner Git history with much less merge commits and no cluttered visual branch merge loops whatsoever.
- Because a
rebasemoves 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
mergeis the better option. But typically, a clean git history is much more useful than exact commit dates.
- 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.
- Rebase often. I typically recommend doing it at least once a day.
- Try to squash changes on the same line into one commit as much as possible.
I hope this FAQ helps some teams out there. Like ❤️ it if you liked it! 😉