From: Matt T. Proud Date: Thu, 3 Oct 2024 07:57:46 +0000 (+0000) Subject: cmd/go: clarify that -coverpkg uses import paths X-Git-Tag: go1.24rc1~571 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=201b9f6d6b46e0ae311e8a8b2cbe2ad6652f5680;p=gostls13.git 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 Reviewed-by: Michael Matloob Auto-Submit: Ian Lance Taylor Reviewed-by: Rob Pike Reviewed-by: Michael Knyszek --- diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index dcb2352bec..71bb838ae1 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 9e3ef58e99..ec1567803f 100644 --- a/src/cmd/go/internal/help/helpdoc.go +++ b/src/cmd/go/internal/help/helpdoc.go @@ -64,6 +64,12 @@ Go library. - "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 @@ By convention, this is arranged by starting each path with a 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 4bc9b5ea4c..58c54c99e0 100644 --- a/src/cmd/go/internal/test/test.go +++ b/src/cmd/go/internal/test/test.go @@ -235,10 +235,10 @@ control the execution of any test: 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 83caea9525..27246436e4 100644 --- a/src/cmd/go/internal/work/build.go +++ b/src/cmd/go/internal/work/build.go @@ -104,10 +104,11 @@ and test commands: 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