Feb 10, 2015 - Sytse Sijbrandij  

GitLab reduced merge conflicts by 90% with changelog placeholders

GitLab has a very active development cycle with many features being added to its monthly release by more than 700 contributors. Like many projects it has a changelog file that details all significant new features, bugfixes and changes to behaviour. Every pull/merge request author is encouraged to add a line to this changelog. Unfortunately, the amount of merge requests lead to a time-consuming problem.



The order in which merge requests are accepted is not know in advance. Most merge request added a new line to the changelog the end of the upcoming version. This meant that upon merging a single merge request, all other unmerged MRs were immediately broken, since they modified the same line. The authors of the merge requests had to solve the merge conflict with a commit or rebase before their code could be merged in the web UI.

Install GitLab on your own server in 2 minutes


ayufan suggested a much better solution in the comments of this article. If you add CHANGELOG merge=union to the .gitattributes file in the root of the repo you should not have any conflicts. Instead of leaving conflicts the union merge option will resolve conflicts favouring both side of the lines. An example of such a setting change is in the endgamesingularity repo. Thanks ayufan, we'll try this instead.


At GitLab we solved the above problem by adding a 100 lines with just a hyphen placeholder at the top of the changelog. People can insert their entry at a random location in the changelog. There is still a chance of conflict when two merge requests change the same line but it is greatly reduced. It looks a bit strange to have these empty lines on top so we added a comment to explain their purpose..

What developer happiness looks like

As part of the monthly release process all the empty lines are removed and new ones for the upcoming release are added. The placeholders ensure that lead GitLab developer Dmitriy can merge new contributions easily from his iPad. Which has led to more late-night merging activity making everyone happy.

What do you do?

We hope this article inspires other open and closed source projects to reduce their merge conflicts. Or if you don't have a changelog yet to start maintaining one, it sure beats doing git diffs all the time. Please let us know if you are inspired or if you have any other tricks to share in the comments.

Install GitLab on your own server in 2 minutes

For the latest and most detailed news follow @gitlab on Twitter. Future blog posts suggestions RSS

Install GitLab in 2 minutes

With Ubuntu, Debian, CentOS and Raspbian packages or from source

Install GitLab Now

Try GitLab Enterprise Edition risk-free for 30 days.

No credit card required. Have questions? Contact us.