What is the `version` in yarn.lock `__metadata`?

Question

At the top of my yarn.lock file I see:

__metadata:
  version: 5
  cacheKey: 8

I have no idea what the version or cacheKey is, and I haven't found any documentation for them on yarn's website. What are they?

Answer 1

It's simply the yarn.lock version, originally introduced here:

When upgraded, the lockfile entries have to be resolved again (but the specific versions are still pinned, no worry). Bump it when you change the fields within the Package type; no more no less.

More details on the currently implemented resolution logic:

github.com/yarnpkg/berry/blob/master/packages/yarnpkg-core/sources/Project.ts

---

Typical scenario

My lockfile version updated locally because my latest Homebrew Yarn version was running behind on 3.2.0-rc.10, despite running brew upgrade and yarn -v still showing this older version.

However a bot (might be team member) already upgraded Yarn to 3.2.0-rc.12, versioned / committed / locked remotely in .yarnrc.yml and npm.packageManager (example).

This is what we want for consistency, so we could add a package.json script to use it instead

// ...
  "scripts": {
    // ...
    "setup": "yarn",
    // ...
// ...

If frequently switching between classic, stable and canary - cd ~ && yarn set version <ver> may bump your local Yarn version too (then remember to clear generated files).