cmd/go/internal/modget: Improve GOINSECURE docs.

Recommend use of GOINSECURE over -insecure flang and clarify that GOINSECURE
environment variable does not also imply GONOSUMDB.

src/cmd/go/alldocs.go

@@ -1017,8 +1017,7 @@
 //
 // Download downloads the named modules, which can be module patterns selecting
 // dependencies of the main module or module queries of the form path@version.
-// With no arguments, download applies to all dependencies of the main module
+// With no arguments, download applies to all dependencies of the main module.
-// (equivalent to 'go mod download all').
 //
 // The go command will automatically download modules as needed during ordinary
 // execution. The "go mod download" command is useful mainly for pre-filling
@@ -2694,15 +2693,15 @@
 // Go module mirror run by Google and fall back to a direct connection
 // if the proxy reports that it does not have the module (HTTP error 404 or 410).
 // See https://proxy.golang.org/privacy for the service's privacy policy.
-//
+// If GOPROXY is set to the string "direct", downloads use a direct connection
-// If GOPROXY is set to the string "direct", downloads use a direct connection to
+// to source control servers. Setting GOPROXY to "off" disallows downloading
-// source control servers. Setting GOPROXY to "off" disallows downloading modules
+// modules from any source. Otherwise, GOPROXY is expected to be a comma-separated
-// from any source. Otherwise, GOPROXY is expected to be list of module proxy URLs
+// list of the URLs of module proxies, in which case the go command will fetch
-// separated by either comma (,) or pipe (|) characters, which control error
+// modules from those proxies. For each request, the go command tries each proxy
-// fallback behavior. For each request, the go command tries each proxy in
+// in sequence, only moving to the next if the current proxy returns a 404 or 410
-// sequence. If there is an error, the go command will try the next proxy in the
+// HTTP response. The string "direct" may appear in the proxy list,
-// list if the error is a 404 or 410 HTTP response or if the current proxy is
+// to cause a direct connection to be attempted at that point in the search.
-// followed by a pipe character, indicating it is safe to fall back on any error.
+// Any proxies listed after "direct" are never consulted.
 //
 // The GOPRIVATE and GONOPROXY environment variables allow bypassing
 // the proxy for selected modules. See 'go help module-private' for details.

src/cmd/go/internal/help/helpdoc.go

@@ -510,6 +510,8 @@ General-purpose environment variables:
 		Comma-separated list of glob patterns (in the syntax of Go's path.Match)
 		of module path prefixes that should always be fetched in an insecure
 		manner. Only applies to dependencies that are being fetched directly.
+		Unlike the -insecure flag on 'go get' this does not disable checksum
+		database validation; please use GOPRIVATE or GONOSUMDB to achieve that.
 	GOOS
 		The operating system for which to compile code.
 		Examples are linux, darwin, windows, netbsd.

src/cmd/go/internal/modget/get.go

@@ -114,7 +114,10 @@ require downgrading other dependencies, and 'go get' does
 this automatically as well.
 
 The -insecure flag permits fetching from repositories and resolving
-custom domains using insecure schemes such as HTTP. Use with caution.
+custom domains using insecure schemes such as HTTP. Use with caution. It is
+recommended to use the GOINSECURE environment variable instead as it allows
+for more fine-grained control when fetching dependencies in this manner. See
+'go help environment' for details.
 
 The second step is to download (if needed), build, and install
 the named packages.