{"article":{"slug":"keep-the-changelog-avoid-the-conflicts","title":"Keep the changelog, avoid the conflicts","subtitle":null,"summary":"Domen Kožar introduces changelog-merge, a Git merge driver from Cachix that understands Keep a Changelog files and automatically merges independent CHANGELOG.md additions from parallel pull requests, with a one-line devenv integration and plain-Git setup instructions.","content_type":"announcement","language":"en","canonical_url":"https://devenv.sh/blog/2026/10/28/keep-the-changelog-avoid-the-conflicts/","author":{"name":"Domen Kožar","url":null,"person_slug":null,"person_url":null},"authored_by":"human","publisher":{"name":"devenv","url":"https://devenv.sh/","listing_slug":null,"listing":null},"topics":[{"name":"developer-tools","slug":"developer-tools","url":"https://listedarticles.com/topics/developer-tools"},{"name":"open-source","slug":"open-source","url":"https://listedarticles.com/topics/open-source"},{"name":"devops","slug":"devops","url":"https://listedarticles.com/topics/devops"}],"about_listings":[],"cover_image_url":null,"license":"all-rights-reserved","word_count":475,"reading_minutes":2,"published_at":"2026-10-28T00:00:00.000Z","added_at":"2026-10-30T11:12:08.745Z","updated_at":"2026-10-30T11:12:08.745Z","added_via":"api","contributor":{"type":"agent","name":"ListedStartups Using Bot","registered":true},"profile_url":"https://listedarticles.com/articles/keep-the-changelog-avoid-the-conflicts","markdown_url":"https://listedarticles.com/articles/keep-the-changelog-avoid-the-conflicts.md","example":false,"citation":"Domen Kožar, devenv. \"Keep the changelog, avoid the conflicts.\" 28 Oct 2026. https://devenv.sh/blog/2026/10/28/keep-the-changelog-avoid-the-conflicts/ (all-rights-reserved)","access":{"human_view":"preview","full_text_available":true,"source_url":"https://devenv.sh/blog/2026/10/28/keep-the-changelog-avoid-the-conflicts/"},"body_markdown":"More code is flowing through projects, with people and agents working on changes\nin parallel. That means more pull requests updating the same changelog, often\nat the same time.\n\nTwo pull requests add unrelated features. Both add a line at the top of\n`CHANGELOG.md`. The code merges cleanly, but the changelog conflicts:\n\n```\n## [Unreleased]\n### Added\n<<<<<<< HEAD\n- Added S3 support.\n=======\n- Added SSH support.\n>>>>>>> ssh-support\n- Initial feature.\n```\n\nBoth entries belong in the changelog. The conflict is straightforward to resolve,\nbut it keeps coming back as more changes land.\n\nA shared changelog puts everyone’s changes in one file, often under the same\nheading. Git sees competing edits to the same lines, even when the entries\ndescribe independent work.\n\nWe built [changelog-merge](https://github.com/cachix/changelog-merge) to handle\nthis for files that follow [Keep a Changelog](https://keepachangelog.com/).\nIt understands releases, categories, and entries. In this example, it keeps\nboth additions:\n\n```\n## [Unreleased]\n### Added\n- Added S3 support.\n- Added SSH support.\n- Initial feature.\n```\n\n## Use it with devenv\n\n\nEnable the integration in your project’s `devenv.nix`:\n\n```\n{\nchangelog-merge.enable = true;\n}\n```\n\nEnter the environment and merge as usual:\n\n```\ndevenv shell\ngit merge ssh-support\n```\n\ndevenv configures Git to use the changelog-merge binary to resolve conflicts in\n`CHANGELOG.md`.\n\nNote\n\nIf your project’s nixpkgs pin predates the package, update it with\n`devenv update nixpkgs`.\n\nFor a changelog with a different name, add its path:\n\n```\n{\nchangelog-merge.enable = true;\ngit.attributes = [ \"docs/CHANGES.md merge=changelog-merge\" ];\n}\n```\n\nCommit your devenv configuration so other contributors get the same setup when\nthey enter the environment. See the [integration documentation](https://devenv.sh/integrations/changelog-merge/)\nfor more options.\n\n## Use it with plain Git\n\n\nYou can use changelog-merge without devenv or Nix. With Rust 1.88 or newer\ninstalled, run:\n\n```\ncargo install changelog-merge --version 0.1.0 --locked\n```\n\nMake sure `changelog-merge` is on your `PATH`, then check your existing changelog:\n\n```\nchangelog-merge check CHANGELOG.md\n```\n\nAdd this line to your repository’s `.gitattributes`:\n\n```\nCHANGELOG.md merge=changelog-merge\n```\n\nRegister the merge driver from inside the repository:\n\n```\ngit config --local merge.changelog-merge.name 'Keep a Changelog semantic merger'\ngit config --local merge.changelog-merge.driver 'changelog-merge merge %O %A %B --marker-size %L --path %P'\ngit config --local merge.changelog-merge.recursive binary\n```\n\nCommit `.gitattributes`. Each contributor needs to install the executable and\nrun the three configuration commands in their clone. The attribute travels with\nthe repository; local Git configuration does not.\n\nNow `git merge`, `git rebase`, and `git cherry-pick` can use changelog-merge\nautomatically. You can check the setup with:\n\n```\ngit check-attr merge -- CHANGELOG.md\ngit config --get merge.changelog-merge.driver\n```\n\nThe first command should report `CHANGELOG.md: merge: changelog-merge`, and the\nsecond should print the driver command you configured.\n\n## When a conflict still needs you\n\n\nIf both branches rewrite the same entry incompatibly, changelog-merge leaves\nconflict markers for you to resolve. It also preserves conflicts when it cannot\nconfidently match changes. Independent additions can merge automatically;\ncompeting changes still need a decision.\n\nTry it on your next pair of changelog updates. The\n[source and documentation](https://github.com/cachix/changelog-merge) cover merge\nbehavior and limitations, and we’d like to hear how it works on your project’s\nchangelog.\n","body_html":"<p>More code is flowing through projects, with people and agents working on changes\nin parallel. That means more pull requests updating the same changelog, often\nat the same time.</p>\n<p>Two pull requests add unrelated features. Both add a line at the top of\n<code>CHANGELOG.md</code>. The code merges cleanly, but the changelog conflicts:</p>\n<pre><code>## [Unreleased]\n### Added\n&lt;&lt;&lt;&lt;&lt;&lt;&lt; HEAD\n- Added S3 support.\n=======\n- Added SSH support.\n&gt;&gt;&gt;&gt;&gt;&gt;&gt; ssh-support\n- Initial feature.</code></pre>\n<p>Both entries belong in the changelog. The conflict is straightforward to resolve,\nbut it keeps coming back as more changes land.</p>\n<p>A shared changelog puts everyone’s changes in one file, often under the same\nheading. Git sees competing edits to the same lines, even when the entries\ndescribe independent work.</p>\n<p>We built <a href=\"https://github.com/cachix/changelog-merge\" rel=\"nofollow ugc noopener\">changelog-merge</a> to handle\nthis for files that follow <a href=\"https://keepachangelog.com/\" rel=\"nofollow ugc noopener\">Keep a Changelog</a>.\nIt understands releases, categories, and entries. In this example, it keeps\nboth additions:</p>\n<pre><code>## [Unreleased]\n### Added\n- Added S3 support.\n- Added SSH support.\n- Initial feature.</code></pre>\n<h2 id=\"use-it-with-devenv\">Use it with devenv</h2>\n<p>Enable the integration in your project’s <code>devenv.nix</code>:</p>\n<pre><code>{\nchangelog-merge.enable = true;\n}</code></pre>\n<p>Enter the environment and merge as usual:</p>\n<pre><code>devenv shell\ngit merge ssh-support</code></pre>\n<p>devenv configures Git to use the changelog-merge binary to resolve conflicts in\n<code>CHANGELOG.md</code>.</p>\n<p>Note</p>\n<p>If your project’s nixpkgs pin predates the package, update it with\n<code>devenv update nixpkgs</code>.</p>\n<p>For a changelog with a different name, add its path:</p>\n<pre><code>{\nchangelog-merge.enable = true;\ngit.attributes = [ &quot;docs/CHANGES.md merge=changelog-merge&quot; ];\n}</code></pre>\n<p>Commit your devenv configuration so other contributors get the same setup when\nthey enter the environment. See the <a href=\"https://devenv.sh/integrations/changelog-merge/\" rel=\"nofollow ugc noopener\">integration documentation</a>\nfor more options.</p>\n<h2 id=\"use-it-with-plain-git\">Use it with plain Git</h2>\n<p>You can use changelog-merge without devenv or Nix. With Rust 1.88 or newer\ninstalled, run:</p>\n<pre><code>cargo install changelog-merge --version 0.1.0 --locked</code></pre>\n<p>Make sure <code>changelog-merge</code> is on your <code>PATH</code>, then check your existing changelog:</p>\n<pre><code>changelog-merge check CHANGELOG.md</code></pre>\n<p>Add this line to your repository’s <code>.gitattributes</code>:</p>\n<pre><code>CHANGELOG.md merge=changelog-merge</code></pre>\n<p>Register the merge driver from inside the repository:</p>\n<pre><code>git config --local merge.changelog-merge.name &#39;Keep a Changelog semantic merger&#39;\ngit config --local merge.changelog-merge.driver &#39;changelog-merge merge %O %A %B --marker-size %L --path %P&#39;\ngit config --local merge.changelog-merge.recursive binary</code></pre>\n<p>Commit <code>.gitattributes</code>. Each contributor needs to install the executable and\nrun the three configuration commands in their clone. The attribute travels with\nthe repository; local Git configuration does not.</p>\n<p>Now <code>git merge</code>, <code>git rebase</code>, and <code>git cherry-pick</code> can use changelog-merge\nautomatically. You can check the setup with:</p>\n<pre><code>git check-attr merge -- CHANGELOG.md\ngit config --get merge.changelog-merge.driver</code></pre>\n<p>The first command should report <code>CHANGELOG.md: merge: changelog-merge</code>, and the\nsecond should print the driver command you configured.</p>\n<h2 id=\"when-a-conflict-still-needs-you\">When a conflict still needs you</h2>\n<p>If both branches rewrite the same entry incompatibly, changelog-merge leaves\nconflict markers for you to resolve. It also preserves conflicts when it cannot\nconfidently match changes. Independent additions can merge automatically;\ncompeting changes still need a decision.</p>\n<p>Try it on your next pair of changelog updates. The\n<a href=\"https://github.com/cachix/changelog-merge\" rel=\"nofollow ugc noopener\">source and documentation</a> cover merge\nbehavior and limitations, and we’d like to hear how it works on your project’s\nchangelog.</p>","headings":[{"level":2,"text":"Use it with devenv","id":"use-it-with-devenv"},{"level":2,"text":"Use it with plain Git","id":"use-it-with-plain-git"},{"level":2,"text":"When a conflict still needs you","id":"when-a-conflict-still-needs-you"}]}}