Łukasz Makuch

So you're working on a PHP project using Composer and a merge conflict occurs on the composer.lock file. How do you merge it? Well, it may sound a bit strange, but the short answer is: You don't.

The composer.lock file is meant to be generated by Composer. It must not be modified in any other way, or it'll become corrupted, and you'll end up installing random stuff. Sometimes. On some machines. Yeah, I know, it sounds horrible, doesn't it?

Composer should be the only tool used to change the composer.lock file. It means it cannot be altered in PhpStorm or Sublime Text. Moreover, even Git should not be used to merge changes into it! Even though it looks like yet another text file, Composer relies on its integrity. And to Git it's, well, just another collection of lines. That's why it makes sense to mark it as a binary file in Git's .gitattributes file:

composer.lock binary

But then what do you do when a conflict does occur? There are two ways to tackle that.

Assuming that you have amazing tests you can completely rely on, then your first option is to accept the changes to the composer.json file, completely remove the composer.lock file, and regenerate it from scratch by running the composer install command. It'll "work", but frankly, that's not why we have the lock file in the first place. It'll result in all the dependencies being updated. And I mean all of them. Of course, they'll be updated only within the constraints set by the composer.json file, but still.

The more down-to-earth approach is to look at what changed in the commit you want to merge and reapply those changes by running commands such as composer require and composer remove. It'll give Composer a chance to protect the integrity of the dependencies and it won't automatically bump the version of everything else.

To sum it up: treat the composer.lock file as if it were an image. You wouldn't use a line-based merging tool to merge different images. And you wouldn't manually edit them in a text editor either (unless you're a 10x developer, of course 😉).

If you'd like to read more about it, there's a great chapter of the docs that touches upon the topic of resolving merge conflicts.