Skip to content

git - change git merge strategy to union for changelog.md and authors.md to prevent recurrent merge conflicts

Robert Sokolewiczrequested to merge
union_merge_changelog_md into main

tldr: no more merge conflicts in CHANGELOG.md and AUTHORS.md.

Often when working on an MR you add an entry to CHANGELOG.md. If something gets merged into main before your MR, you typically merge those changes into your branch by doing a quick git merge origin main. Quite often CHANGELOG.md was modified on the same line as you added your entry and a merge conflict occurs. This can get quite irritating if many branches get merged into main before yours, and every time you merge main into your branch the same merge conflict occurs.

There are different options to combat this. One option is to change the merge strategy for CHANGELOG.md to union by adding a line CHANGELOG.md merge=union to .gitattributes.

Locally I've run the following example and it works beautifully.

Create two branches A_test and B_test. In A_test I have the following lines in CHANGELOG.md:

# Changelog

## Unreleased

### Breaking changes

- small changes to A

in B_test I have

# Changelog

## Unreleased

### Breaking changes

- small changes to B

while in the current branch union_merge_changelog_md there is no entry under Breaking changes.

I run the following:

$ git merge A_test
Updating fc9b58f0..3efc9ae4
Fast-forward
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)
$ git checkout B_test
Switched to branch 'B_test'
$ git merge union_merge_changelog_md 
Auto-merging CHANGELOG.md
Merge made by the 'recursive' strategy.
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

and the resulting merged CHANGELOG.md looks like

# Changelog

## Unreleased

### Breaking changes

- small changes to A
- small changes to B

as expected. I've run the same experiment after removing CHANGELOG.md merge=union from .gitattributes. After which I get the familiar merge-conflict:

$ git merge A_test
Updating 6a93a426..4d48e5d8
Fast-forward
 CHANGELOG.md | 2 ++
 1 file changed, 2 insertions(+)
$ git checkout B_test 
Switched to branch 'B_test'
$ git merge union_merge_changelog_md 
Auto-merging CHANGELOG.md
CONFLICT (content): Merge conflict in CHANGELOG.md
Automatic merge failed; fix conflicts and then commit the result.

I'm trying to think when this could go wrong unexpectedly, but can't think of anything. According to GitLab devs:

This will usually work, but may run into issues if concurrently added features have very similar lines.

but my little experiment does not support this statement.

Merge request reports