cmd/go: revise 'go help' documentation for modules

Module-related help pages now contain a brief summary and point to the
reference documentation at golang.org/ref/mod for details.

Help pages for commands like 'go get' still describe the basic usage
and summarize flags but don't provide as much background detail.

Fixes #41427
Fixes #43419

Change-Id: Icacd38e0f33c352c447cc5a496c99674493abde2
Reviewed-on: https://go-review.googlesource.com/c/go/+/282615
Trust: Jay Conrod <jayconrod@google.com>
Run-TryBot: Jay Conrod <jayconrod@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Bryan C. Mills <bcmills@google.com>

1 files changed, 12 insertions, 96 deletions

diff --git a/src/cmd/go/internal/modfetch/fetch.go b/src/cmd/go/internal/modfetch/fetch.go
index debeb3f319..c55c3cf253 100644
--- a/src/cmd/go/internal/modfetch/fetch.go
+++ b/src/cmd/go/internal/modfetch/fetch.go
@@ -768,90 +768,14 @@ var HelpModuleAuth = &base.Command{
 	UsageLine: "module-auth",
 	Short:     "module authentication using go.sum",
 	Long: `
-The go command tries to authenticate every downloaded module,
-checking that the bits downloaded for a specific module version today
-match bits downloaded yesterday. This ensures repeatable builds
-and detects introduction of unexpected changes, malicious or not.
-
-In each module's root, alongside go.mod, the go command maintains
-a file named go.sum containing the cryptographic checksums of the
-module's dependencies.
-
-The form of each line in go.sum is three fields:
-
-	<module> <version>[/go.mod] <hash>
-
-Each known module version results in two lines in the go.sum file.
-The first line gives the hash of the module version's file tree.
-The second line appends "/go.mod" to the version and gives the hash
-of only the module version's (possibly synthesized) go.mod file.
-The go.mod-only hash allows downloading and authenticating a
-module version's go.mod file, which is needed to compute the
-dependency graph, without also downloading all the module's source code.
-
-The hash begins with an algorithm prefix of the form "h<N>:".
-The only defined algorithm prefix is "h1:", which uses SHA-256.
-
-Module authentication failures
-
-The go command maintains a cache of downloaded packages and computes
-and records the cryptographic checksum of each package at download time.
-In normal operation, the go command checks the main module's go.sum file
-against these precomputed checksums instead of recomputing them on
-each command invocation. The 'go mod verify' command checks that
-the cached copies of module downloads still match both their recorded
-checksums and the entries in go.sum.
-
-In day-to-day development, the checksum of a given module version
-should never change. Each time a dependency is used by a given main
-module, the go command checks its local cached copy, freshly
-downloaded or not, against the main module's go.sum. If the checksums
-don't match, the go command reports the mismatch as a security error
-and refuses to run the build. When this happens, proceed with caution:
-code changing unexpectedly means today's build will not match
-yesterday's, and the unexpected change may not be beneficial.
-
-If the go command reports a mismatch in go.sum, the downloaded code
-for the reported module version does not match the one used in a
-previous build of the main module. It is important at that point
-to find out what the right checksum should be, to decide whether
-go.sum is wrong or the downloaded code is wrong. Usually go.sum is right:
-you want to use the same code you used yesterday.
-
-If a downloaded module is not yet included in go.sum and it is a publicly
-available module, the go command consults the Go checksum database to fetch
-the expected go.sum lines. If the downloaded code does not match those
-lines, the go command reports the mismatch and exits. Note that the
-database is not consulted for module versions already listed in go.sum.
-
-If a go.sum mismatch is reported, it is always worth investigating why
-the code downloaded today differs from what was downloaded yesterday.
-
-The GOSUMDB environment variable identifies the name of checksum database
-to use and optionally its public key and URL, as in:
-
-	GOSUMDB="sum.golang.org"
-	GOSUMDB="sum.golang.org+<publickey>"
-	GOSUMDB="sum.golang.org+<publickey> https://sum.golang.org"
-
-The go command knows the public key of sum.golang.org, and also that the name
-sum.golang.google.cn (available inside mainland China) connects to the
-sum.golang.org checksum database; use of any other database requires giving
-the public key explicitly.
-The URL defaults to "https://" followed by the database name.
-
-GOSUMDB defaults to "sum.golang.org", the Go checksum database run by Google.
-See https://sum.golang.org/privacy for the service's privacy policy.
-
-If GOSUMDB is set to "off", or if "go get" is invoked with the -insecure flag,
-the checksum database is not consulted, and all unrecognized modules are
-accepted, at the cost of giving up the security guarantee of verified repeatable
-downloads for all modules. A better way to bypass the checksum database
-for specific modules is to use the GOPRIVATE or GONOSUMDB environment
-variables. See 'go help private' for details.
-
-The 'go env -w' command (see 'go help env') can be used to set these variables
-for future go command invocations.
+When the go command downloads a module zip file or go.mod file into the
+module cache, it computes a cryptographic hash and compares it with a known
+value to verify the file hasn't changed since it was first downloaded. Known
+hashes are stored in a file in the module root directory named go.sum. Hashes
+may also be downloaded from the checksum database depending on the values of
+GOSUMDB, GOPRIVATE, and GONOSUMDB.
+
+For details, see https://golang.org/ref/mod#authenticating.
 `,
 }
 
@@ -865,8 +789,8 @@ regardless of source, against the public Go checksum database at sum.golang.org.
 These defaults work well for publicly available source code.
 
 The GOPRIVATE environment variable controls which modules the go command
-considers to be private (not available publicly) and should therefore not use the
-proxy or checksum database. The variable is a comma-separated list of
+considers to be private (not available publicly) and should therefore not use
+the proxy or checksum database. The variable is a comma-separated list of
 glob patterns (in the syntax of Go's path.Match) of module path prefixes.
 For example,
 
@@ -876,10 +800,6 @@ causes the go command to treat as private any module with a path prefix
 matching either pattern, including git.corp.example.com/xyzzy, rsc.io/private,
 and rsc.io/private/quux.
 
-The GOPRIVATE environment variable may be used by other tools as well to
-identify non-public modules. For example, an editor could use GOPRIVATE
-to decide whether to hyperlink a package import to a godoc.org page.
-
 For fine-grained control over module download and validation, the GONOPROXY
 and GONOSUMDB environment variables accept the same kind of glob list
 and override GOPRIVATE for the specific decision of whether to use the proxy
@@ -892,12 +812,6 @@ users would configure go using:
 	GOPROXY=proxy.example.com
 	GONOPROXY=none
 
-This would tell the go command and other tools that modules beginning with
-a corp.example.com subdomain are private but that the company proxy should
-be used for downloading both public and private modules, because
-GONOPROXY has been set to a pattern that won't match any modules,
-overriding GOPRIVATE.
-
 The GOPRIVATE variable is also used to define the "public" and "private"
 patterns for the GOVCS variable; see 'go help vcs'. For that usage,
 GOPRIVATE applies even in GOPATH mode. In that case, it matches import paths
@@ -905,5 +819,7 @@ instead of module paths.
 
 The 'go env -w' command (see 'go help env') can be used to set these variables
 for future go command invocations.
+
+For more details, see https://golang.org/ref/mod#private-modules.
 `,
 }