Avoiding merge bubbles

Eric S. Raymond esr at thyrsus.com
Sat Jul 2 13:06:16 UTC 2016

This is a request for people doing development on a branch, or merges from
GitLab.  It was prompted by Hal Murray's commit of 2016-07-01 23: "Merge 
branch 'master' of gitlab.com:NTPsec/ntpsec" which left a bubble in the
commit history.  To see it, view the repository with gitk; you'll see a
bubble with 10 commits from me on one side and one from Hal Murray
on the other

I strongly dislike having trivial merge bubbles like this one in the history.
Now I'm going to explain why, and how to avoid them.  This will become more
relevant as more pepple contribute to the code.

Sometimes a merge bubble conveys real information.  This is so when the
commits on either side of it don't actually commute - a nontrivial merge,
with actual editing out of conflicts, is required to reconcile the two
lines of development. In this case, a bubble in the commit graph is

Hal's merge had no such conflicts. His side of the bubble and mine didn't
even touch the same files.  This is the usual case.

I strongly dislike trivial merge bubbles precisely because they
mislead later readers about where merge conficts occurred. Real merge
conflicts are important events with a significant tendency to attract
defects later on - they mean two developers, possibly with
incompatible models of how the code should work, have collided.  I
think it's important not to lose them in clutter created by trivial
merge bubbles.

More generally, a git history that is as close to linear as real merge
conflicts allow is easier to read and run bisections on.

The NTP Classic repo is a pretty horrifying example of what happens
when you don't exercise this hygiene - it's so bubbly that the main line
of development is nigh-impossible to track.

So please avoid creating trivial merge bubbles.  The recipe for this is
very simple: just before you push a commit to the public repo, do this:

git pull --rebase

What this will do is pull any public commits you don't have onto master,
then attempt to replay your local changes onto the tip of master. 99% of
the time this will just work.  You can then "git push" and your commits
will become a linear addition to the public history.

In the very rare cases this doesn't work, you'll have to do a conflict
merge before pushing.  When you do this, don't settle for an automatically
generated merge comment like this:

    Merge branch 'master' of gitlab.com:NTPsec/ntpsec

Instead, try to make your merge comment as informative as possible about
the actual conflict.

Thanks in advance for your cooperation.
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

More information about the devel mailing list