cmd/go/tool: tool directive with local relative path replace

[dnaeon]

Go version

go version go1.25.1 darwin/arm64

Output of go env in your module/workspace:

AR='ar'
CC='cc'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='c++'
GCCGO='gccgo'
GO111MODULE='on'
GOARCH='arm64'
GOARM64='v8.0'
GOAUTH='netrc'
GOBIN='/Users/abc/workspace/Projects/golang/bin'
GOCACHE='/Users/abc/Library/Caches/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/Users/abc/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOHOSTARCH='arm64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMOD='/dev/null'
GOMODCACHE='/Users/abc/workspace/Projects/golang/cache'
GONOPROXY=''
GONOSUMDB=''
GOOS='darwin'
GOPATH='/Users/abc/workspace/Projects/golang'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/opt/homebrew/Cellar/go/1.25.1/libexec'
GOSUMDB='sum.golang.org'
GOTELEMETRY='local'
GOTELEMETRYDIR='/Users/abc/Library/Application Support/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/opt/homebrew/Cellar/go/1.25.1/libexec/pkg/tool/darwin_arm64'
GOVCS=''
GOVERSION='go1.25.1'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

There appears to be an issue with how go tool interprets relative replace statements when used in combination with -modfile flag.

Here's an example, which can be used to reproduce the issue.

Create a new Go module.

  mkdir go-tool-modfile-replace
  cd go-tool-modfile-replace
  go mod init go-tool-modfile-replace

Create a dummy tool, which we will use.

  mkdir -p cmd/dummy
  cd cmd/dummy
  go mod init my/dummy/cmd

This is how cmd/dummy/main.go looks like.

package main

import (
	"fmt"
	"os"
)

func main() {
	pwd, err := os.Getwd()
	if err != nil {
		panic(err)
	}
	fmt.Printf("dummy was called. cwd is %s\n", pwd)
}

Next, create a dedicated tools module, which will be used for tracking various tool dependencies. These tools may be related to anything the project uses as part of the lifecycle, e.g. linting, formatting, etc. It will also include our simple dummy tool.

  repo-root $ mkdir -p tools
  tools $ cd tools
  tools $ go mod init my/tools/mod

We can now add any tools we need using go get -tool, and dependencies will be tracked correctly. However, we want to include our dummy tool as well, so that we can call each utility tool via go tool <name>.

This is what tools/go.mod looks like, when it contains only our dummy tool.

module my/tools/mod

go 1.25.1

tool my/dummy/cmd

replace my/dummy/cmd => ../cmd/dummy

require my/dummy/cmd v0.0.0-00010101000000-000000000000 // indirect

Now we can run our dummy tool when we are within the tools/ directory (module).

tools $ go tool my/dummy/cmd
dummy was called. cwd is /Users/abc/go-tool-modfile-replace/tools

However, if we go back to the repo root and try to call the tool it would fail.

repo-root $ go tool -modfile tools/go.mod my/dummy/cmd
my/dummy/cmd: my/dummy/cmd@v0.0.0-00010101000000-000000000000: replacement directory ../cmd/dummy does not exist

The reason it fails here is (probably) because the relative path replace in tools/go.mod is relative to the current directory of the calling process, instead of being relative to the path where tools/go.mod resides.

If we use go tool -C tools my/dummy/cmd the command would work fine, but only because the current directory will already be set (via the -C flag), and the replace statement would be valid, because our current workdir is the same as the location for go.mod as well.

go tool -C tools my/dummy/cmd
dummy was called. cwd is /Users/abc/go-tool-modfile-replace/tools

What did you see happen?

Please see details above.

What did you expect to see?

Calling go tool -modfile path/to/go.mod some-tool should work fine when the path/to/go.mod contains local relative replace entries.

When using relative replace entries with relative local paths, perhaps the paths should be relative to the directory of the go.mod file itself.

For example when calling go tool -modfile path/to/go.mod some-tool any local relative replace entries in path/to/go.mod should be considered relative in regards to the path/to directory, which contains the go.mod file.

[seankhliao]

This is working as intended.
relative paths in go.mod refer to the module root,
-modfile essentially overwites the contents of the current module root, disregarding wherever the module file came from, they aren't a means for you to work across module boundaries.

[dnaeon]

Hey @seankhliao ,

-modfile essentially overwites the contents of the current module root, disregarding wherever the module file came from, they aren't a means for you to work across module boundaries.

Is this documented somewhere?

The following two commands are equivalent:

repo-root$ cd some/path && go tool some-tool
repo-root$ go tool -C some/path some-tool

However, when using -modfile one would assume that it's similar to the previous commands, since you specify the path to a separate go.mod, and replace should work as expected.

go tool -modfile some/path/go.mod some-tool

... but this doesn't work when some/path/go.mod contains replace directive, since in this case local replacements are not relative to the replacement module.

Looking at the go.mod file reference for replace directive.

replacement-path
The path at which Go should look for the required module. This can be a module path or a path to a directory on the file system local to the replacement module. If this is a module path, you must specify a replacement-version value. If this is a local path, you may not use a replacement-version value.

From the docs above it seems that either the docs are incorrect or misleading, or go tool -modfile ... doesn't work as expected.

[seankhliao]

The docs for modfile:

in module aware mode, read (and possibly write) an alternate go.mod
file instead of the one in the module root directory. A file named
"go.mod" must still be present in order to determine the module root
directory, but it is not accessed. When -modfile is specified, an
alternate go.sum file is also used: its path is derived from the
-modfile flag by trimming the ".mod" extension and appending ".sum".

The module root doesn't change, so you're still in the original module, and paths must be relative to the module root.

[dnaeon]

I'm guessing that the paragraph, which is supposed to make this clear is this one.

A file named "go.mod" must still be present in order to determine the module root directory, but it is not accessed.

... which to me is vague. What does "but it is not accessed" here mean? Technically speaking you are "accessing the directory" each time you read/write from/to it, so perhaps a better wording here would be something like this instead.

A file named "go.mod" must still be present in order to determine the module root directory, but the original module root does not change.

A note about potential use of replace directive in the go.mod specified by -modfile would be nice as well, just to warn users about the potential side effects.

@seankhliao , what do you think?