cmd/go: unclear what ImportMap in "list -json" means

[mvdan]

$ go version
go version devel +974def803e Tue Nov 3 04:11:02 2020 +0000 linux/amd64
$ go help list | grep ImportMap
        ImportMap    map[string]string // map from source import to ImportPath (identity entries omitted)

I've been writing Go tools and using Go modules for years, and I can't understand what this field means, or when it's used.

My initial suspicion was that it mattered for vendored dependencies, because a user reported a go list -json output containing:

	"ImportMap": {
		"golang.org/x/crypto/internal/subtle": "vendor/golang.org/x/crypto/internal/subtle"
	},

However, I just created a simple module with vendored dependencies, and go list -json -deps does not show any ImportMap. I also had a brief look at the cmd/go code, and it seems like the map can contain RawImports (no idea what those are either), or imports like runtime/cgo which appear only in generated code.

Could we clarify the docs a bit on this? I realise that the doc line should still be one line, but perhaps we can expand on its definition in the text after the type definition, just like the paragraph starting with Packages stored in vendor directories report an ImportPath....

[mvdan]

Digging a bit further, the original change was in mid-2018 at https://go-review.googlesource.com/c/go/+/122878/, presumably to better support foo.test packages for #25949. Unfortunately, the commit message doesn't really clarify much for me.

[mvdan]

Ah, it seems like ImportMap is used for vendored packages in the standard library, but not in the current module:

$ go list -json vendor/golang.org/x/text/secure/bidirule | grep -A3 ImportMap
	"ImportMap": {
		"golang.org/x/text/transform": "vendor/golang.org/x/text/transform",
		"golang.org/x/text/unicode/bidi": "vendor/golang.org/x/text/unicode/bidi"
	},

This seems to be what I was running into. It's still unclear to me why vendored packages only appear in ImportMap in this case, but not others.

[bcmills]

ImportMap used to be more significant: in GOPATH mode with per-package vendor directories, it reported the mapping of import paths to vendor trees.

In module mode it is indeed less useful, because we now have only one copy of each module dependency (instead of one per vendor subtree). However, it will probably become a bit more meaningful again once we get replacements straightened out (#26904, #30831).

[mvdan]

Thanks; at least this confirms that my being confused at the docs is somewhat justified :) I'm happy to have this issue in the backlog until those two issues are fixed. Once they are, perhaps the docs can be clarified with an example or two.

[dominikh]

On the topic of confusion: #46462