// importpath import path syntax
// modules modules, module versions, and more
// module-get module-aware go get
-// packages package lists and patterns
// module-auth module authentication using go.sum
+// module-private module configuration for non-public modules
+// packages package lists and patterns
// testflag testing flags
// testfunc testing functions
//
// For more details see: 'go help gopath'.
// GOPROXY
// URL of Go module proxy. See 'go help modules'.
-// GONOPROXY
+// GOPRIVATE, GONOPROXY, GONOSUMDB
// Comma-separated list of glob patterns (in the syntax of Go's path.Match)
-// of module path prefixes that should always be fetched directly, ignoring
-// the GOPROXY setting. See 'go help modules'.
+// of module path prefixes that should always be fetched directly
+// or that should not be compared against the checksum database.
+// See 'go help module-private'.
+// GOROOT
+// The root of the go tree.
// GOSUMDB
// The name of checksum database to use and optionally its public key and
// URL. See 'go help module-auth'.
-// GONOSUMDB
-// Comma-separated list of glob patterns (in the syntax of Go's path.Match)
-// of module path prefixes that should not be compared against the checksum
-// database. See 'go help module-auth'.
-// GOROOT
-// The root of the go tree.
// GOTMPDIR
// The directory where the go command will write
// temporary source files, packages, and binaries.
// to cause a direct connection to be attempted at that point in the search.
// Any proxies listed after "direct" are never consulted.
//
-// The GONOPROXY environment variable is a comma-separated list of
-// glob patterns (in the syntax of Go's path.Match) of module path prefixes
-// that should always be fetched directly, ignoring the GOPROXY setting.
-// For example,
-//
-// GONOPROXY=*.corp.example.com,rsc.io/private
-//
-// forces a direct connection to download modules with path prefixes matching
-// either pattern, including "git.corp.example.com/xyzzy", "rsc.io/private",
-// and "rsc.io/private/quux".
-//
-// The 'go env -w' command (see 'go help env') can be used to set these variables
-// for future go command invocations.
+// The GOPRIVATE and GONOPROXY environment variables allow bypassing
+// the proxy for selected modules. See 'go help module-private' for details.
//
// No matter the source of the modules, the go command checks downloads against
// known checksums, to detect unexpected changes in the content of any specific
// are still ignored.
//
//
-// Package lists and patterns
-//
-// Many commands apply to a set of packages:
-//
-// go action [packages]
-//
-// Usually, [packages] is a list of import paths.
-//
-// An import path that is a rooted path or that begins with
-// a . or .. element is interpreted as a file system path and
-// denotes the package in that directory.
-//
-// Otherwise, the import path P denotes the package found in
-// the directory DIR/src/P for some DIR listed in the GOPATH
-// environment variable (For more details see: 'go help gopath').
-//
-// If no import paths are given, the action applies to the
-// package in the current directory.
-//
-// There are four reserved names for paths that should not be used
-// for packages to be built with the go tool:
-//
-// - "main" denotes the top-level package in a stand-alone executable.
-//
-// - "all" expands to all packages found in all the GOPATH
-// trees. For example, 'go list all' lists all the packages on the local
-// system. When using modules, "all" expands to all packages in
-// the main module and their dependencies, including dependencies
-// needed by tests of any of those.
-//
-// - "std" is like all but expands to just the packages in the standard
-// Go library.
-//
-// - "cmd" expands to the Go repository's commands and their
-// internal libraries.
-//
-// Import paths beginning with "cmd/" only match source code in
-// the Go repository.
-//
-// An import path is a pattern if it includes one or more "..." wildcards,
-// each of which can match any string, including the empty string and
-// strings containing slashes. Such a pattern expands to all package
-// directories found in the GOPATH trees with names matching the
-// patterns.
-//
-// To make common patterns more convenient, there are two special cases.
-// First, /... at the end of the pattern can match an empty string,
-// so that net/... matches both net and packages in its subdirectories, like net/http.
-// Second, any slash-separated pattern element containing a wildcard never
-// participates in a match of the "vendor" element in the path of a vendored
-// package, so that ./... does not match packages in subdirectories of
-// ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do.
-// Note, however, that a directory named vendor that itself contains code
-// is not a vendored package: cmd/vendor would be a command named vendor,
-// and the pattern cmd/... matches it.
-// See golang.org/s/go15vendor for more about vendoring.
-//
-// An import path can also name a package to be downloaded from
-// a remote repository. Run 'go help importpath' for details.
-//
-// Every package in a program must have a unique import path.
-// 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'.
-//
-// Packages in a program need not have unique package names,
-// but there are two reserved package names with special meaning.
-// The name main indicates a command, not a library.
-// Commands are built into binaries and cannot be imported.
-// The name documentation indicates documentation for
-// a non-Go program in the directory. Files in package documentation
-// are ignored by the go command.
-//
-// As a special case, if the package list is a list of .go files from a
-// single directory, the command is applied to a single synthesized
-// package made up of exactly those files, ignoring any build constraints
-// in those files and ignoring any other files in the directory.
-//
-// Directory and file names that begin with "." or "_" are ignored
-// by the go tool, as are directories named "testdata".
-//
-//
// Module authentication using go.sum
//
// The go command tries to authenticate every downloaded module,
// 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 GONOSUMDB environment variable.
+// for specific modules is to use the GOPRIVATE or GONOSUMDB environment
+// variables. See 'go help module-private' for details.
+//
+// The 'go env -w' command (see 'go help env') can be used to set these variables
+// for future go command invocations.
+//
+//
+// Module configuration for non-public modules
//
-// The GONOSUMDB environment variable is a comma-separated list of
-// glob patterns (in the syntax of Go's path.Match) of module path prefixes
-// that should not be compared against the checksum database.
+// The go command defaults to downloading modules from the public Go module
+// mirror at proxy.golang.org. It also defaults to validating downloaded modules,
+// 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
+// glob patterns (in the syntax of Go's path.Match) of module path prefixes.
// For example,
//
-// GONOSUMDB=*.corp.example.com,rsc.io/private
+// GOPRIVATE=*.corp.example.com,rsc.io/private
+//
+// 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
+// and checksum database, respectively.
+//
+// For example, if a company ran a module proxy serving private modules,
+// users would configure go using:
+//
+// GOPRIVATE=*.corp.example.com
+// GOPROXY=proxy.example.com
+// GONOPROXY=none
//
-// disables checksum database lookups for modules with path prefixes matching
-// either pattern, including "git.corp.example.com/xyzzy", "rsc.io/private",
-// and "rsc.io/private/quux".
+// This would tell the go comamnd 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 'go env -w' command (see 'go help env') can be used to set these variables
// for future go command invocations.
//
//
+// Package lists and patterns
+//
+// Many commands apply to a set of packages:
+//
+// go action [packages]
+//
+// Usually, [packages] is a list of import paths.
+//
+// An import path that is a rooted path or that begins with
+// a . or .. element is interpreted as a file system path and
+// denotes the package in that directory.
+//
+// Otherwise, the import path P denotes the package found in
+// the directory DIR/src/P for some DIR listed in the GOPATH
+// environment variable (For more details see: 'go help gopath').
+//
+// If no import paths are given, the action applies to the
+// package in the current directory.
+//
+// There are four reserved names for paths that should not be used
+// for packages to be built with the go tool:
+//
+// - "main" denotes the top-level package in a stand-alone executable.
+//
+// - "all" expands to all packages found in all the GOPATH
+// trees. For example, 'go list all' lists all the packages on the local
+// system. When using modules, "all" expands to all packages in
+// the main module and their dependencies, including dependencies
+// needed by tests of any of those.
+//
+// - "std" is like all but expands to just the packages in the standard
+// Go library.
+//
+// - "cmd" expands to the Go repository's commands and their
+// internal libraries.
+//
+// Import paths beginning with "cmd/" only match source code in
+// the Go repository.
+//
+// An import path is a pattern if it includes one or more "..." wildcards,
+// each of which can match any string, including the empty string and
+// strings containing slashes. Such a pattern expands to all package
+// directories found in the GOPATH trees with names matching the
+// patterns.
+//
+// To make common patterns more convenient, there are two special cases.
+// First, /... at the end of the pattern can match an empty string,
+// so that net/... matches both net and packages in its subdirectories, like net/http.
+// Second, any slash-separated pattern element containing a wildcard never
+// participates in a match of the "vendor" element in the path of a vendored
+// package, so that ./... does not match packages in subdirectories of
+// ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do.
+// Note, however, that a directory named vendor that itself contains code
+// is not a vendored package: cmd/vendor would be a command named vendor,
+// and the pattern cmd/... matches it.
+// See golang.org/s/go15vendor for more about vendoring.
+//
+// An import path can also name a package to be downloaded from
+// a remote repository. Run 'go help importpath' for details.
+//
+// Every package in a program must have a unique import path.
+// 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'.
+//
+// Packages in a program need not have unique package names,
+// but there are two reserved package names with special meaning.
+// The name main indicates a command, not a library.
+// Commands are built into binaries and cannot be imported.
+// The name documentation indicates documentation for
+// a non-Go program in the directory. Files in package documentation
+// are ignored by the go command.
+//
+// As a special case, if the package list is a list of .go files from a
+// single directory, the command is applied to a single synthesized
+// package made up of exactly those files, ignoring any build constraints
+// in those files and ignoring any other files in the directory.
+//
+// Directory and file names that begin with "." or "_" are ignored
+// by the go tool, as are directories named "testdata".
+//
+//
// Testing flags
//
// The 'go test' command takes both flags that apply to 'go test' itself
`
-var HelpSum = &base.Command{
+var HelpModuleAuth = &base.Command{
UsageLine: "module-auth",
Short: "module authentication using go.sum",
Long: `
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 GONOSUMDB environment variable.
+for specific modules is to use the GOPRIVATE or GONOSUMDB environment
+variables. See 'go help module-private' for details.
-The GONOSUMDB environment variable is a comma-separated list of
-glob patterns (in the syntax of Go's path.Match) of module path prefixes
-that should not be compared against the checksum database.
+The 'go env -w' command (see 'go help env') can be used to set these variables
+for future go command invocations.
+`,
+}
+
+var HelpModulePrivate = &base.Command{
+ UsageLine: "module-private",
+ Short: "module configuration for non-public modules",
+ Long: `
+The go command defaults to downloading modules from the public Go module
+mirror at proxy.golang.org. It also defaults to validating downloaded modules,
+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
+glob patterns (in the syntax of Go's path.Match) of module path prefixes.
For example,
- GONOSUMDB=*.corp.example.com,rsc.io/private
+ GOPRIVATE=*.corp.example.com,rsc.io/private
+
+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
+and checksum database, respectively.
+
+For example, if a company ran a module proxy serving private modules,
+users would configure go using:
+
+ GOPRIVATE=*.corp.example.com
+ GOPROXY=proxy.example.com
+ GONOPROXY=none
-disables checksum database lookups for modules with path prefixes matching
-either pattern, including "git.corp.example.com/xyzzy", "rsc.io/private",
-and "rsc.io/private/quux".
+This would tell the go comamnd 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 'go env -w' command (see 'go help env') can be used to set these variables
for future go command invocations.