cmd/go: -coverpkg documentation is too oblique about import paths

[matttproud]

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.

[gabyhelp]

Related Issues and Documentation

• cmd/covdata: percent does not support ./... for the -pkg pattern #66507
• cmd/go: coverpkg flag should be part of cache key #66504
• cmd/go: -coverpkg=all is not useful #10271 (closed)
• cmd/covdata: percent does not support -coverpkg #66464
• cmd/go: go 1.22.0: go test throws errors when processing folders not listed in coverpkg argument #65653 (closed)
• cmd/go: coverpkg doesn't ignore directories starting with '.' #66038
• cmd/go: -coverpkg=all gives different coverage value when run on a package list vs ./... #23883 (closed)
• Unintuitive behavior when using -coverpkg #23786 (closed)
• proposal: cmd/go: coverpkg should default to the package list #32939
• cmd/cover: inconsistent treatment of main package in coverage reports #57169 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[gopherbot]

Change https://go.dev/cl/616257 mentions this issue: cmd/go: clarify that -coverpkg uses import paths