This is a custom Git merge driver that you can use to avoid conflicts when merging changelogs. It provides a clean and elegant solution to a problem that even the whole GitLab team struggled with, when they created this ugly hack.
The changelogs must adhere to the format specified by Keep a Changelog. On top of this format, some additional features are supported. See Changelog Format Extensions.
There are two ways to run it. Both use the same sources and behave identically, so pick whichever fits your setup.
-
Install JBang (if not already available)
-
Configure the merge driver in Git:
$ git config --global merge.changelog.driver "jbang changelog-merge-driver@maven-flow/changelog-merge-driver %A %O %B" $ git config --global merge.changelog.name "Merge driver for changelogs"
Note
JBang fetches and builds the driver on first use, so there is no manual JDK or jar to download and no path to keep track of.
-
Ensure that Java 17+ is available, e.g. by installing a JDK.
-
Download the merge driver jar or clone this repository and build it by running
mvn package. -
Configure the merge driver in Git:
$ git config --global merge.changelog.driver "java -jar <path_to_driver_jar> %A %O %B" $ git config --global merge.changelog.name "Merge driver for changelogs"
Tell Git to use the merge driver by adding a .gitattributes file into your repository with the following content:
**/CHANGELOG.md merge=changelog
There is also an automatic merge GitHub action that utilizes this merge driver.
Normal mode is useful for merging feature branches into develop. It works as follows:
-
Take
ourschangelog file and use it as a base. -
Take all versions from
theirsthat are missing inoursand put them intooursbefore (on top of) the already present versions. -
Merge the released versions which are present in both
oursandtheirs. See Merging Released Versions. -
Merge the changelog header. See Merging the Changelog Header.
The first version in the changelog may be marked as Unreleased. This version is treated in a special way:
-
If
ourscontains an unreleased version andtheirscontains new released versions, all changes from the released versions will be merged also into the unreleased version in chronological order (older versions first). See Merging Versions.- To prevent duplications, a change is added only if it was not already released in
ours(if non of the released version inourscontains the change). - Added changes are prefixed with a label indicating which released version they have been added from. For example:
[from `1.0.0`] New feature
- To prevent duplications, a change is added only if it was not already released in
-
If
ourscontains an unreleased version andtheirsalso contains an unreleased version, the unreleased version fromtheirswill be merged into the unreleased version inours(see Merging Versions). -
If
oursdoes not contain an unreleased version buttheirsdoes, the unreleased version fromtheirsis copied intoours.
NOTE: This kind of merging is only applied to unreleased versions. Released versions present in both files are merged line-based instead (see Merging Released Versions).
Each version is separated into sections ("Added", "Changed", "Fixed", "Removed", etc.) and each sections contains items (lines). The versions are merged by sections, which means that their "Added" section is merged into our "Added" section, their "Changed" section is merged into our "Changed" section, etc.
When merging sections, items (lines) from theirs section are added into ours section after the items already present in ours section. Adding duplicates is avoided (if an item from theirs is already present in ours, it is not added again).
If a section from theirs is not present in ours, it is copied into ours.
A released version which is present in both files is merged line by line, using the version from the Git merge base (the %O file) as the common ancestor, similar to a standard Git merge:
-
A change made only in
oursor only intheirs(for example a typo fix) is applied. -
Identical changes made in both files are applied once.
-
Lines added at the same place in both files are kept from both,
oursfirst. -
If both files changed the same lines differently, the lines from
theirsare used. Unlike a standard Git merge, no conflict is reported: for released versions, the changelog being merged in is considered authoritative.
If the merge base does not contain the version, or the base file is not a parsable changelog (which happens when the changelog was created independently on both branches), there is nothing to compare against and the version is kept as a whole: from ours in normal mode, from theirs in rebase mode.
The changelog header (the caption and the description above the first version) is merged with the same line-based three-way merge as released versions, so a header change made in only one file is preserved and theirs wins where both files changed the same lines differently. Without a parsable base file, the header is kept as a whole: from ours in normal mode, from theirs in rebase mode.
Example of merging 2 changelog files in normal mode can be found here.
Rebase mode is useful for updating a feature branch with the latest changes from the target branch. It is activated by using the flag --rebase.
-
Take
theirschangelog file and use it as a base. -
Take all changes from
ourunreleased version and add them into the base. -
Merge the released versions which are present in both files (see Merging Released Versions), so non-conflicting changes made to them in the feature branch are preserved; where both branches changed the same lines,
theirswins (see Limitations). Released versions only present intheirsare left unchanged. -
Merge the changelog header (see Merging the Changelog Header) with the same rules, so non-conflicting header changes made in the feature branch are preserved as well.
On top of the standard format defined in Keep a Changelog, this merge driver supports additional changelog features:
The standard format specifies that unreleased versions should be defined with name [Unreleased] and without a specific number. This merge driver also supports specifying numbers for unreleased versions, and also using the word "SNAPSHOT", which is equivalent to "Unreleased". The check is not case-sensitive.
These are all valid forms of specifying an unreleased version:
[Unreleased][UNRELEASED]UnreleasedUNRELEASED[1.0.0] - Unreleased[1.0.0] - [Unreleased][Snapshot][SNAPSHOT]SnapshotSNAPSHOT[1.0.0] - SNAPSHOT[1.0.0] - [SNAPSHOT][1.0.0-SNAPSHOT]
Versions can have a generic block of text before the standard sections.
For example:
## [1.0.0] - 2024-04-27
This is a generic version description.
More than one line is supported.
### Added
- Added featureFor the sake of simplicity and performance, the merge driver has the following limitations. This may be changed in the future, if needed.
-
If both sides changed the same lines of a released version or of the changelog header differently, the lines from
theirsare used (see Merging Released Versions). The merge driver never reports a conflict. If you want to resolve such conflicts by hand, you have to perform a standard Git merge. -
Newly added versions are not sorted in any way. They are always considered to be newer than the already present versions, and therefore are always added to the top. This approach generally works without issues, given that the changelogs are being merged regularly.
Other interesting tools dealing with changelog are listed below:
- heylogs checks the format (including link consistency) and more.