cmd/go: document that go env GOMOD can return /dev/null

[myitcv]

What version of Go are you using (go version)?

$ go version
go version devel +da4d58587e Sat Dec 7 15:57:30 2019 +0000 linux/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GO111MODULE=""
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/myitcv/.cache/go-build"
GOENV="/home/myitcv/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/myitcv/gostuff"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/myitcv/gos"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/myitcv/gos/pkg/tool/linux_amd64"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build492256999=/tmp/go-build -gno-record-gcc-switches"

What did you do?

The docs for GOMOD state:

$ go help environment
...
        GOMOD
                The absolute path to the go.mod of the main module,
                or the empty string if not using modules.

For some time I have (incorrectly) been advising people that the way to determine if you are in a module context or not (i.e. modules not off and you are in the context of a go.mod) is by testing whether the output from go env GOMOD is the empty string or not.

However this fails when you consider:

$ cd $(mktemp -d)
$ GO111MODULE=on go env GOMOD
/dev/null

It's also not clear the docs are quite correct when it comes to modules being not off (i.e. auto or on):

$ cd $(mktemp -d)
$ go env GOMOD
 

(i.e. empty string, but we aren't not using modules, we are in the auto mode. Granted this is a bit less clearly incorrect)

I realise that this way go env GOMOD can be used to determine whether modules are off/not off, and whether you are in a module context or not assuming that they are not off. But documenting this a bit more clearly would, I think, help (selfishly me at least).

Because the actual logic for correctly determining that modules are not off and you are in a module context is:

cmd := exec.Command("go", "env", "GOMOD")
out, _ := cmd.CombinedOutput()
gomod := strings.TrimSpace(string(out))
if gomod != "" and gomod != os.DevNull {
   // ....

Thoughts?

cc @bcmills @jayconrod

FYI @mvdan @kortschak

[mvdan]

It took Paul and I a good ten minutes to figure out what the right logic is, so I definitely agree that this isn't clear enough in the docs.

[thepudds]

To my knowledge, the longest bit of documentation might be in the Go 1.12 release notes:

When GO111MODULE is set to on, the go command now supports module-aware operations outside of a module directory, provided that those operations do not need to resolve import paths relative to the current directory or explicitly edit the go.mod file. Commands such as go get, go list, and go mod download behave as if in a module with initially-empty requirements. In this mode, go env GOMOD reports the system's null device (/dev/null or NUL).

From what I have seen, I am not sure that /dev/null lines up with people's intuitions, especially for people who are new to modules.

[gopherbot]

Change https://golang.org/cl/210577 mentions this issue: cmd/go: document 'go env GOMOD' outside modules