3 simple steps to avoid recurring merge conflicts

3 simple steps to avoid recurring merge conflicts

Until recently, I made my otherwise joyful developer life harder than it needed to be. And no, I haven’t run out of coffee. It’s worse: recurring merge conflicts.

More specifically, I’m talking about conflicts caused by version updates in files such as pom.xml or package.json when you maintain multiple release branches at the same time. One branch gets a new release number, another has its own version changes, and suddenly an otherwise straightforward merge needs manual attention again.

Here’s the approach that helped: keep routine version bumps out of the long-lived branches that you regularly merge together.

3 simple steps to avoid recurring version conflicts

1. Keep the version stable on long-lived release branches

Instead of incrementing the package version directly on release/1, release/2 and main every time you ship, leave a stable development version on each line.

For example, a Maven project might use 1.0.0-SNAPSHOT on release/1 and 2.0.0-SNAPSHOT on release/2, with the exact published version set during the release process. The precise value must be valid for your build tool.

Important: the original 1.x and 2.x examples were shorthand for major-version lines, not literal values to copy into a package file. In particular, npm’s package.json version field requires a valid SemVer version—not "1.x".

2. Set the actual version in a one-way release branch

When it’s time to publish version 1.8.4, create a short-lived branch from the appropriate release line—for example, publish/1.8.4 from release/1.

Set the real version (1.8.4) and any related package or lockfile metadata on that publishing branch, then build, test, tag and publish the release from the exact versioned commit. The tag gives you a way to identify the source of the released artifact later.

Don’t merge the version-only publishing branch back into release/1, release/2 or main. Keep the real bug fixes and feature changes on the normal development branches instead.

If your build system can supply a release version at build time—for example, Maven’s CI-friendly ${revision} support—you may not need a separate publishing branch at all.

3. Propagate code fixes forward, without the release-only version bump

You can now carry an applicable fix from an older maintained line through the newer ones—for example:

bugfix → release/1 → release/2 → main

Because the release-only version change never enters those shared branches, it can’t introduce a recurring version-number conflict during that propagation.

This doesn’t mean every forward-merge will be conflict-free. Actual code changes, dependencies and lockfiles may still conflict, and some fixes need adapting for newer releases. It simply removes one avoidable source of repeated conflict.

A small change to your release process can save repeated cleanup

Nobody likes merge conflicts—especially ones caused by version numbers rather than real disagreements in the code. If you’re maintaining multiple release lines, check whether your version-bump commits are being merged between them unnecessarily.

The principle is simple: keep development branches stable, give published artifacts their exact versions, and propagate real code changes—not release-only version bumps.

For other types of conflicts, see our advanced Git merge conflict resolution techniques, including rerere for repeated manual resolutions.

Managing release pull requests in Bitbucket?

This Git branching approach addresses version-related conflicts, not pull request review policy. If you’re also looking to standardise who reviews release changes and which approvals or builds are required before merge, explore Workzone for Bitbucket on the Atlassian Marketplace.

By Sean Manwarring, Head of Marketing at Izymes
Published 16 November 2022 · Updated 26 October 2026