cmd/go: -coverpkg documentation is too oblique about import paths #69653
Description
Go version
go version go1.23-20240626-RC01 cl/646990413 +5a18e79687 X:fieldtrack,boringcrypto linux/amd64
Output of go env in your module/workspace:
GO111MODULE=''
GOARCH='amd64'
GOBIN=''
GOCACHE='/usr/local/google/home/mtp/.cache/go-build'
GOENV='/usr/local/google/home/mtp/.config/go/env'
GOEXE=''
GOEXPERIMENT='fieldtrack,boringcrypto'
GOFLAGS=''
GOHOSTARCH='amd64'
GOHOSTOS='linux'
GOINSECURE=''
GOMODCACHE='/usr/local/google/home/mtp/go/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='linux'
GOPATH='/usr/local/google/home/mtp/go'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/usr/lib/google-golang'
GOSUMDB='sum.golang.org'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/usr/lib/google-golang/pkg/tool/linux_amd64'
GOVCS=''
GOVERSION='go1.23-20240626-RC01 cl/646990413 +5a18e79687 X:fieldtrack,boringcrypto'
GODEBUG=''
GOTELEMETRY='local'
GOTELEMETRYDIR='/usr/local/google/home/mtp/.config/go/telemetry'
GCCGO='gccgo'
GOAMD64='v1'
AR='ar'
CC='clang'
CXX='clang++'
CGO_ENABLED='1'
GOMOD='/dev/null'
GOWORK=''
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
PKG_CONFIG='pkg-config'
GOGCCFLAGS='-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=/tmp/go-build2230501016=/tmp/go-build -gno-record-gcc-switches'What did you do?
I ran go help testflag and go help build to understand how to adjust the code coverage package specification parameters to ensure certain packages were included or excluded from code coverage analysis.
What did you see happen?
go help testflag emitted a fragment similar to this:
...
-coverpkg pattern1,pattern2,pattern3
Apply coverage analysis in each test to packages matching the patterns.
The default is for each test to analyze only the package being tested.
See 'go help packages' for a description of package patterns.
Sets -cover.
...
go help build emitted a fragment similar to this:
-coverpkg pattern1,pattern2,pattern3
For a build that targets package 'main' (e.g. building a Go
executable), apply coverage analysis to each package matching
the patterns. The default is to apply coverage analysis to
packages in the main Go module. See 'go help packages' for a
description of package patterns. Sets -cover.
...
What did you expect to see?
The text as written for both -coverpkg flags mentions the word "package" in a rather oblique way such that a casual reader of the text would infer the meaning of "package" to refer to a package name and not the import path, when in truth the pattern used by both of these flags also can select packages based on import paths.
I had wanted specialized coverage analysis based on several import paths and not simple package names (unqualified) for a development task I was doing, and I found the current documentation as written confusing in this regard. The external documentation referred to with "go help packages" helps to be sure, but a quick read of the original help output for these flags would erroneously lead a reader to assume that import paths are not supported.
I would like to propose the verbiage is changed to include mention of import paths. There are several ways this can be done. I have put together a small proposal in a changelist that I'll submit shortly.