Is "content-hash" a mandatory part of composer.lock?

Question

Like most people writing (and reading) the question about whether to keep composer.lock in version-control, we keep ours there.

However, this causes us trouble every time the file is independently updated in different code-branches. Even when the changes are unrelated and affect the sections of the file afar from each other, the "content-hash" line is causing a conflict every time. Worse, neither "side" is correct and whoever is doing the merging must regenerate the file by hand...

Maybe, the line is not really necessary? Before asking, whether (the current version of) composer will work without it, what functionality would be missing? The hash seems to guard against the file itself changing -- but the source-control system is already doing that...

Can I simply remove the line? If it can not be done today, would it be a desirable feature for composer?

Answer 1

Purpose of the content hash

As you can see in Composer\Package\Locker::getContentHash(), the content hash takes into account the following fields of composer.json:

$relevantKeys = array(     'name',     'version',     'require',     'require-dev',     'conflict',     'replace',     'provide',     'minimum-stability',     'prefer-stable',     'repositories',     'extra', ); 

The only reason for the content hash to change is a change of one of the values of the corresponding properties in composer.json.

Composer uses the content hash to determine whether relevant fields in composer.json are in sync with composer.lock. You can run

$ composer validate 

to find out if they are in sync.

If composer.json and composer.lock are not in sync, a message similar to this will be shown

The lock file is not up to date with the latest changes in composer.json, it is recommended that you run composer update.

For reference, see https://getcomposer.org/doc/03-cli.md#validate:

You should always run the validate command before you commit your composer.json file, and before you tag a release. It will check if your composer.json is valid.

Resolving conflicts in composer.lock

If you have trouble resolving conflicts in composer.lock, maybe this helps:

Step 1: Accept upstream changes

Usually, you will probably attempt to rebase a branch on top of the upstream changes. When already in conflict, use your IDE, or run

$ git checkout --theirs composer.lock 

to accept the upstream changes to composer.lock. Since this is a generated file, you really don't want to resolve conflicts in it.

Step 2: Re-apply changes to composer.json and composer.lock

As pointed out earlier, there are a range of the relevant keys in composer.json. Some of them can be modified by corresponding commands, others cannot.

For example, if one of the changes is a newly added or removed package, run

$ composer require foo/bar:^1.2.3 

or

$ composer remove foo/bar 

to apply the changes.

If the changes cannot be applied by running a command, manually modify composer.json, then run

$ composer update --lock 

This will update the content hash.

For reference, see https://getcomposer.org/doc/03-cli.md#update:

--lock: Only updates the lock file hash to suppress warning about the lock file being out of date.