php - What does "locked at" <tag> mean when running "composer update <package>"?

Question

I am trying to perform a composer update <package> but getting the following error:

The requested package <package> (locked at <tag>, required as <version>) is satisfiable by <package>[<tag>] but these conflict with your requirements or minimum-stability.

Meanwhile, the tag <tag> exists as a string only in my composer.lock file, which I thought was only modified by composer update, not read back.

I tried running composer why-not <package>, but its output didn't really explain the issue:

<program> <other-version> requires <package> (<version>)

What does 'locked at' mean in this context and how do I solve the issue?

Answer 1

The package is locked means the commit-hash of the last commit on the branch used with version-constraint dev-<branch> was saved during the last run of composer update in the lock-file to ensure deterministic (reproducible) builds upon deployment.

This commit-hash or tag is written to your lock-file (composer.lock) if you:

1. run composer update [<package>]

... or ...

2. run composer install with a composer.json present but not a lock-file in composer's current directory which does auto-generate the lock-file