Resolving merge conflicts#
When working as a team on the same Composer project, you will eventually run into a scenario
where multiple people added, updated or removed something in the
composer.lock files in multiple branches. When those branches are eventually merged
together, you will get merge conflicts. Resolving these merge conflicts is not as straight
forward as on other files, especially not regarding the
Note: It might not immediately be obvious why text based merging is not possible for lock files, so let's imagine the following example where we want to merge two branches;
- Branch 1 has added package A which requires package B. Package B is locked at version
- Branch 2 has added package C which conflicts with all versions below
1.2.0of package B.
A text based merge would result in package A version
1.0.0, package B version
1.0.0and package C version
1.0.0. This is an invalid result, as the conflict of package C was not considered and would require an upgrade of package B.
1. Reapplying changes#
The safest method to merge Composer files is to accept the version from one branch and apply the changes from the other branch.
An example where we have two branches:
- Package 'A' has been added
- Package 'B' has been removed and package 'C' is added.
To resolve the conflict when we merge these two branches:
- We choose the branch that has the most changes, and accept the
composer.lockfiles from that branch. In this case, we choose the composer files from branch 2.
- We reapply the changes from the other branch (branch 1). In this case we have to run
composer require package/Aagain.
2. Validating your merged files#
Before committing, make sure the resulting
composer.lock files are valid.
To do this, run the following commands:
composer validate composer install [--dry-run]
Keep in mind that whenever merge conflicts occur on the lock file, the information about the exact version
new packages were locked on for one of the branches gets lost. When package A in branch 1 is constrained
^1.2.0 and locked as
1.2.0, it might get updated when branch 2 is used as baseline and a new
composer require package/A:^1.2.0 is executed, as that will use the most recent version that the
constraint allows when possible. There might be a version 1.3.0 for that package available by now, which
will now be used instead.
Choosing the correct version constraints and making sure the packages adhere to semantic versioning when using next significant release operators should make sure that merging branches does not break anything by accidentally updating a dependency.
Found a typo? Something is wrong in this documentation? Fork and edit it!