Go: cmd/go: document that filesystem-based replace directives require that the right hand side have a go.mod

[grantwwu]

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

$ go version
go version go1.12 darwin/amd64

Does this issue reproduce with the latest release?

I believe 1.12 is the latest release

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

go env Output

$ go env

GOARCH="amd64"

GOBIN=""

GOCACHE="/Users/grant.wu/Library/Caches/go-build"

GOEXE=""

GOFLAGS=""

GOHOSTARCH="amd64"

GOHOSTOS="darwin"

GOOS="darwin"

GOPATH="/Users/grant.wu/go"

GOPROXY=""

GORACE=""

GOROOT="/usr/local/Cellar/go/1.12/libexec"

GOTMPDIR=""

GOTOOLDIR="/usr/local/Cellar/go/1.12/libexec/pkg/tool/darwin_amd64"

GCCGO="gccgo"

CC="clang"

CXX="clang++"

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 -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/rm/k4qc6x917tdf1ms2f8t2jw1h0000gp/T/go-build926919438=/tmp/go-build -gno-record-gcc-switches -fno-common"

What did you do?

At work we internally have a fork of a particular module - call it foo. We have a fork of foo internally for some minor changes. I had the fork checked out at my desired branch at ./grant_modules_hack/vendor/foo. (I was attempting to work around a private repo problem at the time).

I added this replace directive:

replace github.com/someorg/foo => ./grant_modules_hack/vendor/foo

What did you expect to see?

I expected this to work, with, say, go build.

What did you see instead?

go: parsing grant_modules_hack/vendor/foo/go.mod: open /Users/grant.wu/petuum/file-api/src/file-api/grant_modules_hack/vendor/foo/go.mod: no such file or directory
go: error loading module requirements

@thepudds confirmed to me that filesystem-based replace directives do require that the right hand side have a go.mod.

This should definitely be documented somewhere: I don't see this caveat listed anywhere here https://github.com/golang/go/wiki/Modules#when-should-i-use-the-replace-directive

[grantwwu]

This is likely related to https://github.com/golang/go/issues/24110

@rsc states that this is "working as intended", but it doesn't seem obvious to me why the stated rationale applies - after all, go modules interop with non-go module adopting libraries fine outside of replace directives.

In fact without the replace directive, if I want to use the public, non-forked version of said dependency, go modules seems to work with it fine...

[thepudds]

A related comment from Bryan:

replace directives in the local filesystem require a go.mod file: otherwise we have no idea what import paths within that filesystem tree mean. (We need the module directive in the go.mod file in order to know which import paths are internal to the module.)

replace directives that point to other modules should not require a go.mod file, because we can use the module path from which the module was resolved to determine its import prefix.

[bsiegert]

FWIW, I think having a filesystem-based replace without a go.mod on the right-hand side is actually useful.

I was expecting to use that for the following case:

I have a large, curated existing GOPATH, made up of operating system packages for various Go libraries and to be used for builds of other OS packages (that's NetBSD pkgsrc, if you are wondering). Now I would like to replace a given module with its equivalent in the existing GOPATH.

Because we are early in the development of modules, most of these have no go.mod of their own. Running go mod init does not seem like a good option, as it will do more network accesses during the build, which I would like to avoid. Also, I see a danger that this will make other builds depending on the code in the GOPATH break, because now they might switch to module mode.

Or am I thinking about this the wrong way?

[peter-mogensen]

So,.... I've been bitten by #26366 for CGO-using module X, which is really annoying. I had hoped I could then just define a project local GOPATH= and have my main package in /src/main-package and have /src/X ... but no. GOPATH also stops working when GO111MODULE=on.
Then, I had hoped I could vendor module X outside of the go mod controlled vendor dir by using replace X => ../X in go.mod. (here using git subtree)
Unfortunately this runs into this bug, since module X doesn't have a go.mod.

All I wanted here was for go build -mod=vendor to find module X in it's complete form. Can it really be true that we have to introduce yet-another-tool to make this work. I had hoped to just use git and go.