go.sum Is Not a Lockfile

Summary

I need everyone to stop looking at go.sum, especially to analyze dependency graphs. It is not a “lockfile,” and it has zero semantic effects on version resolution. There is truly no use case for ever parsing it outside of cmd/go. go.sum is only a local cache for the Go Checksum Database. It’s a map of module versions to their cryptographic hashes. Those versions may or may not be in use; it doesn’t matter to package resolution. go.sum was not even enabled by default in the original modules design, precisely because it has no observable effect on builds! Its (important) purpose is exclusively tightening the security story: the Checksum Database ensures the whole ecosystem shares the same contents for a given module version, regardless of how it is downloaded, and go.sum makes that guarantee local and self-contained. Instead, just look at go.mod. It lists the precise version at which all dependencies are built. Since Go 1.17 (released August 2021), it includes all transitive dependencies needed to build the main module and its tests. You can either parse go.mod with golang.org/x/mod/modfile, run go mod edit -json to get its JSON representation, or parse it according to its specification. This is the end of the Public Service Announcement. Read on for some go.mod nerdery. Manifests and lockfiles The enduring confusion around go.mod and go.sum is due to the fact that most other languages also have two package-related files, but theirs both matter to version resolution. These two files are usually called manifest and lockfile. The manifest (e.g. pyproject.toml, package.json, Cargo.toml) usually lists some dependencies along with potentially complex rules for which versions are supported. These rules usually apply transitively to dependents, making version resolution extremely hard and/or slow in the general case, and sometimes unsolvable. The manifest is not always guaranteed to list all direct dependencies, and no automated mechanism ensures your code actually works wit...