Skip to content

About

A GIT Merge Driver for Change Logs

Resources

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

Git Changelog Merge Driver

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.

Setup

There are two ways to run it. Both use the same sources and behave identically, so pick whichever fits your setup.

Install with JBang

  1. Install JBang (if not already available)

  2. 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.

Install with a Jar

  1. Ensure that Java 17+ is available, e.g. by installing a JDK.

  2. Download the merge driver jar or clone this repository and build it by running mvn package.

  3. 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"

Enable the Merge Driver in Your Repository (Both Ways)

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.

How It Works (Normal Mode)

Normal mode is useful for merging feature branches into develop. It works as follows:

  • Take ours changelog file and use it as a base.

  • Take all versions from theirs that are missing in ours and put them into ours before (on top of) the already present versions.

  • Merge the released versions which are present in both ours and theirs. See Merging Released Versions.

  • Merge the changelog header. See Merging the Changelog Header.

Unreleased Versions

The first version in the changelog may be marked as Unreleased. This version is treated in a special way:

  • If ours contains an unreleased version and theirs contains 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 in ours contains 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
  • If ours contains an unreleased version and theirs also contains an unreleased version, the unreleased version from theirs will be merged into the unreleased version in ours (see Merging Versions).

  • If ours does not contain an unreleased version but theirs does, the unreleased version from theirs is copied into ours.

Merging Versions

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.

Merging Released Versions

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 ours or only in theirs (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, ours first.

  • If both files changed the same lines differently, the lines from theirs are 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.

Merging the Changelog Header

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 (Normal Mode)

Example of merging 2 changelog files in normal mode can be found here.

How It Works (Rebase Mode)

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 theirs changelog file and use it as a base.

  • Take all changes from our unreleased 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, theirs wins (see Limitations). Released versions only present in theirs are 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.

Changelog Format Extensions

On top of the standard format defined in Keep a Changelog, this merge driver supports additional changelog features:

Marking Unreleased Versions

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]
  • Unreleased
  • UNRELEASED
  • [1.0.0] - Unreleased
  • [1.0.0] - [Unreleased]
  • [Snapshot]
  • [SNAPSHOT]
  • Snapshot
  • SNAPSHOT
  • [1.0.0] - SNAPSHOT
  • [1.0.0] - [SNAPSHOT]
  • [1.0.0-SNAPSHOT]

Version Descriptions

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 feature

Limitations

For 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 theirs are 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.

Related Work

Other interesting tools dealing with changelog are listed below:

  • heylogs checks the format (including link consistency) and more.

About

A GIT Merge Driver for Change Logs

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages