The Composer merge conflicts dilemma

4 min readApr 17, 2023

If you have stumbled upon this page, it’s likely that you are all too familiar with the nasty composer.lock git conflict.

The messageyou read and know you’r f*cked’up

You know, that frustrating and time-consuming problem that can drive you crazy, may lose others developers works such as added, removed or updated packages and leave you feeling like you’re stuck in a never-ending game of whack-a-mole.

Merging Git conflicts, what a lovely task to do

In this article, I will share some of the methods that you may be used to resolve composer.lockgit merge conflict.
By following these methods, you can save yourself from the same headache and make your life a bit easier.

The Prohibited Protocol

I’ve seen some developers try to tackle composer.lock merge conflicts in some very interesting ways.

The best solution to handle merge-conflict, is to delegate

For instance, some have used git checkout --ours composer.lock and then pushed those changes directly to the branch.
While this might seem like a quick fix, it actually overwrites all the other developers’ changes with yours. Essentially, it’s like force-pushing your changes — a big no-no!

Another commonly considered option (though not a good one) is to delete the composer.lock file and create a new one with composer update.
While this might seem like a viable solution if you’re feeling adventurous and don’t really care about the locked versions, it’s important to keep in mind that this approach can result in unforeseen changes to your feature branch and generate unnecessary diffs.
A common outcome of using this approach is that all your dependencies get updated to their latest version without you even realizing it.

Method N°1: The Content Conundrum

Whenever I see a merge conflict in my composer.lock, it’s usually because of that pesky little content-hash. This key is a unique fingerprint for all the dependencies.

Example of merge conflict into composer.lock on the `content-hash key`

When I spot that the only conflict is with the content-hash, I know it’s an easy fix.

In this case, all you have to do is:

Delete all the Git confusion (the HEAD, == and << chars)
Pick one of the two content-hash values — it doesn’t matter which
Run this magic command

composer update --lock

Problem solved!

Method N°2: The Revision Reverberation

Sometimes composer.lock can get so messy and confusing with a gazillion changes, versions, and hash updates.

When I find myself in this sticky situation, I’ve found that it’s better to start fresh by adding or removing the packages on top of the latest changes from the source branch.

It’s like giving your composer.lock a fresh makeover, and it’s so much better than trying to play Sherlock Holmes and figure out the tangled mess of changes!

First, accept the changes from base (main) branch:

git checkout --theirs composer.lock composer.json

Then, re-play all the packages you added, updated or removed in your feature branch:

composer require package/a:^1.2
composer require package/b:^2.0
composer remove package/c
composer require --dev package/d
composer update package/x

When you’re done, make sure your composer.json and composer.lock files are valid using composer validate command.

Problem solved!

Method N°3: The Composer Convergence

If you want to keep those locked versions intact and avoid a whole lot of extra diff drama, you can use an external tool like the Composer Git Merge Driver.

This bad boy automates the merge process and makes sure everything stays organized and in its place. Check out the official repository for all the juicy installation and usage deets.

Sources

Ion Bazan (Apr, 2021) Efficiently resolving composer.lock merge conflicts.
https://dev.to/ionbazan/efficiently-resolving-composer-lock-merge-conflicts-1peb

Mike Madison(Aug, 2020) Resolving composer.lock git merge conflicts.
https://mikemadison.net/blog/2020/8/18/resolving-composerlock-git-merge-conflicts

ChatGPT (2023)
http://chat.openapi.com

Midjourney (2023)
https://midjourney.com