doc: clarify that godebug in go.mod is ignored when using a workspace in favor of go.work's godebug

[pgimalac]

Go version

1.23.6 and 1.24.0

Output of go env in your module/workspace:

AR='ar'
CC='clang'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='clang++'
GCCGO='gccgo'
GO111MODULE='auto'
GOARCH='arm64'
GOARM64='v8.0'
GOAUTH='netrc'
GOBIN=''
GOCACHE='/Users/pierre.gimalac/Library/Caches/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/Users/pierre.gimalac/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -ffile-prefix-map=/var/folders/zp/m8h1x16s30g3f656sxsdt7rm0000gp/T/go-build4235974089=/tmp/go-build -gno-record-gcc-switches -fno-common'
GOHOSTARCH='arm64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMOD='/tmp/iy4pULX4rXgOq5Il/go.mod'
GOMODCACHE='/Users/pierre.gimalac/go/pkg/mod'
GONOPROXY='github.com/DataDog'
GONOSUMDB='github.com/DataDog,go.ddbuild.io'
GOOS='darwin'
GOPATH='/Users/pierre.gimalac/go'
GOPRIVATE='github.com/DataDog'
GOPROXY='binaries.ddbuild.io,proxy.golang.org,direct'
GOROOT='/usr/local/go'
GOSUMDB='sum.golang.org'
GOTELEMETRY='local'
GOTELEMETRYDIR='/Users/pierre.gimalac/Library/Application Support/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/usr/local/go/pkg/tool/darwin_arm64'
GOVCS=''
GOVERSION='go1.24.0'
GOWORK='/tmp/iy4pULX4rXgOq5Il/go.work'
PKG_CONFIG='pkg-config'

What did you do?

The godebug directives in the go.mod file of the main package are ignored when using a workspace.

I'm not sure if this is a bug or on purpose, but if it's on purpose I feel like it should be clearer in the documentation, and possibly warned explicitly when running a go command.

The following piece of sentence appears twice in the documentation https://go.dev/doc/godebug, but it's not clear to me that go.mod is ignored when using a go.work.

[...] the work module’s go.mod or the workspace’s go.work [...]

Reproducible example

Consider the following main.go, it prints the value of the godebug setting panicnil.

package main

import "fmt"

func main() {
	defer func() {
		if r := recover(); r != nil {
			fmt.Println("panicnil=0")
		} else {
			fmt.Println("panicnil=1")
		}
	}()
	panic(nil)
}

Create a go.mod file with a godebug directive for panicnil:

module mytest

go 1.23.6

godebug panicnil=1

And a go.work without said directive:

go 1.23.6

use .

Then run the code with and without workspace:

$ go run main.go
panicnil=0
$ GOWORK=off go run main.go
panicnil=1

The directive in the go.mod file is ignored when using a workspace.

Alternatively using go list also shows the diff:

$ go list -f '{{.DefaultGODEBUG}}'
$ GOWORK=off go list -f '{{.DefaultGODEBUG}}'
panicnil=1

What did you see happen?

The directive in the go.mod file is ignored when using a workspace.

What did you expect to see?

I expected the godebug directive in the go.mod to be used, or in the worst case scenario a warning about it being ignored due to using a workspace.
(or even just improve the documentation to make this case clear)

[gabyhelp]

Related Issues

• compiler detects module based on current working directory #68043 (closed)
• cmd/go: default godebug settings not recorded for test binaries #68053 (closed)
• cmd/go: provide a better error message when no modules exist in workspace #49594 (closed)
• x/tools/go/analysis/passes/directive: spurious requirement for blank line between `//go:debug` and package declaration #66046 (closed)
• cmd/go/internal/work: panic for a repeated //go:debug directive for the same setting #62346 (closed)
• x/tools/gopls: deprecate the "allowModfileModifications" setting #56570 (closed)
• cmd/go: reject the `-modfile` flag in workspace mode #59996 (closed)
• runtime/debug: BuildSetting does not document DefaultGODEBUG #66465 (closed)
• x/website: ref/mod still references the deleted -workfile flag #51838 (closed)

Related Documentation

• Go Modules Reference > Workspaces > godebug directive

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[pgimalac]

Ah very good bot, the "related documentation" https://go.dev/ref/mod#go-work-file-godebug does say

When a workspace is in use, godebug directives in go.mod files are ignored.

Should the other doc https://go.dev/doc/godebug be updated to reflect this too ?

[ianlancetaylor]

CC @matloob @samthanawalla

[gopherbot]

Change https://go.dev/cl/655158 mentions this issue: doc: update godebug doc to clarify godebug directive in workspace