What does the go.work.sum file track in Go 1.18?

Question

I just tried out the Go 1.18 workspace on an existing project. Consider the following project directory structure:

project-root/
|-- app/
|  |-- go.mod
|  |-- go.sum

Per documentation, I ran the command go work init ./app within the root directory of the project. This command created a go.work file as expected, but it also created a go.work.sum file that was not expected.

What's confusing is that go.work.sum references two modules that can be found in go.sum, but the version of each module is not the same when compared between go.sum and go.work.sum. Then there is also the question why are only these two modules referenced in go.work.sum but none of the other ones? Note that there is only the one module within the workspace.

What does the go.work.sum file track? Is it documented anywhere?

Picky

Answer 1

The go.work.sum file is mentioned in the related feature proposal (and seemingly nowhere else?):

https://go.googlesource.com/proposal/+/master/design/45713-workspace.md#files

The go command will use the collective set of go.sum files that exist across the workspace modules to verify dependency modules, but there are cases where the go.sum files in the workspace modules collectively do not contain all sums needed to verify the build: The simpler case is if the workspace go.mod files themselves are incomplete, the go command will add missing sums to the workspace‘s go.work.sum file rather than to the module’s go.sum.

The proposal (same link as above) also describes one more use case where neither of the individual projects import packages from some particular version of a module, but require it as indirect dependency, thus missing the checksum for the module's code.

So your sub-modules may show one of these situations. If it's the former, I'd expect running go mod tidy on the sub-modules puts everything in sync and removes the need for go.work.sum. Based on your description, it sounds like it's the latter instead, then go.work.sum is necessary to track the missing checksums.

Bing

I have created an issue in the Go repo to transfer the documentation on go.work.sum from the proposal to the official docs: github.com/golang/go/issues/51941 – Picky