cmd/go: clarify that -coverpkg uses import paths
This change amends the long-form help output for 'go help build' and
'go help testflag' to specify that the '-coverpkg' flag operates
explicitly on import paths as well as package names. Import paths are
fundamental for precise specification of packages versus unqualified
package names, and the naming of the flag '-coverpkg' and its original
documentation leads a user to assume that it only operates on the
simple, unqualified package name form. The situation warrants
clarification.
Fixes #69653
Change-Id: Ifde6a974405ce1614e28898fc2b92ed5bad94e57
GitHub-Last-Rev: 466c662a70d13560f2fb7affb0d7d900889c7aa7
GitHub-Pull-Request: golang/go#69655
Reviewed-on: https://go-review.googlesource.com/c/go/+/616257
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Michael Matloob <matloob@golang.org>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Rob Pike <r@golang.org>
Reviewed-by: Michael Knyszek <mknyszek@google.com>
diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index dcb2352..71bb838 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -146,10 +146,11 @@
// Sets -cover.
// -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.
+// executable), apply coverage analysis to each package whose
+// import path matches 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.
// -v
// print the names of packages as they are compiled.
// -work
@@ -2953,6 +2954,12 @@
// - "cmd" expands to the Go repository's commands and their
// internal libraries.
//
+// Package names match against fully-qualified import paths or patterns that
+// match against any number of import paths. For instance, "fmt" refers to the
+// standard library's package fmt, but "http" alone for package http would not
+// match the import path "net/http" from the standard library. Instead, the
+// complete import path "net/http" must be used.
+//
// Import paths beginning with "cmd/" only match source code in
// the Go repository.
//
@@ -2982,7 +2989,10 @@
// unique prefix that belongs to you. For example, paths used
// internally at Google all begin with 'google', and paths
// denoting remote repositories begin with the path to the code,
-// such as 'github.com/user/repo'.
+// such as 'github.com/user/repo'. Package patterns should include this prefix.
+// For instance, a package called 'http' residing under 'github.com/user/repo',
+// would be addressed with the fully-qualified pattern:
+// 'github.com/user/repo/http'.
//
// Packages in a program need not have unique package names,
// but there are two reserved package names with special meaning.
@@ -3099,10 +3109,10 @@
// Sets -cover.
//
// -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.
+// Apply coverage analysis in each test to packages whose import paths
+// match 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.
//
// -cpu 1,2,4
// Specify a list of GOMAXPROCS values for which the tests, benchmarks or
diff --git a/src/cmd/go/internal/help/helpdoc.go b/src/cmd/go/internal/help/helpdoc.go
index 9e3ef58..ec15678 100644
--- a/src/cmd/go/internal/help/helpdoc.go
+++ b/src/cmd/go/internal/help/helpdoc.go
@@ -64,6 +64,12 @@
- "cmd" expands to the Go repository's commands and their
internal libraries.
+Package names match against fully-qualified import paths or patterns that
+match against any number of import paths. For instance, "fmt" refers to the
+standard library's package fmt, but "http" alone for package http would not
+match the import path "net/http" from the standard library. Instead, the
+complete import path "net/http" must be used.
+
Import paths beginning with "cmd/" only match source code in
the Go repository.
@@ -93,7 +99,10 @@
unique prefix that belongs to you. For example, paths used
internally at Google all begin with 'google', and paths
denoting remote repositories begin with the path to the code,
-such as 'github.com/user/repo'.
+such as 'github.com/user/repo'. Package patterns should include this prefix.
+For instance, a package called 'http' residing under 'github.com/user/repo',
+would be addressed with the fully-qualified pattern:
+'github.com/user/repo/http'.
Packages in a program need not have unique package names,
but there are two reserved package names with special meaning.
diff --git a/src/cmd/go/internal/test/test.go b/src/cmd/go/internal/test/test.go
index 4bc9b5e..58c54c9 100644
--- a/src/cmd/go/internal/test/test.go
+++ b/src/cmd/go/internal/test/test.go
@@ -235,10 +235,10 @@
Sets -cover.
-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.
+ Apply coverage analysis in each test to packages whose import paths
+ match 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.
-cpu 1,2,4
Specify a list of GOMAXPROCS values for which the tests, benchmarks or
diff --git a/src/cmd/go/internal/work/build.go b/src/cmd/go/internal/work/build.go
index 83caea9..2724643 100644
--- a/src/cmd/go/internal/work/build.go
+++ b/src/cmd/go/internal/work/build.go
@@ -104,10 +104,11 @@
Sets -cover.
-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.
+ executable), apply coverage analysis to each package whose
+ import path matches 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.
-v
print the names of packages as they are compiled.
-work
