From c1956e23e18fbbf06836f1ab9f4b4e10c893b0a9 Mon Sep 17 00:00:00 2001 From: imxyb Date: Wed, 30 Dec 2020 10:17:20 +0800 Subject: [PATCH] help: add doc for GO111MODULE. Fixes #43419 --- src/cmd/go/alldocs.go | 461 +++++++++------------------- src/cmd/go/internal/help/helpdoc.go | 10 + 2 files changed, 155 insertions(+), 316 deletions(-) diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index 78f114f6afe3b1..68bad3cff1b812 100644 --- a/src/cmd/go/alldocs.go +++ b/src/cmd/go/alldocs.go @@ -49,11 +49,10 @@ // modules modules, module versions, and more // module-get module-aware go get // module-auth module authentication using go.sum +// module-private module configuration for non-public modules // packages package lists and patterns -// private configuration for downloading non-public code // testflag testing flags // testfunc testing functions -// vcs controlling version control with GOVCS // // Use "go help " for more information about that topic. // @@ -72,7 +71,7 @@ // // Usage: // -// go build [-o output] [build flags] [packages] +// go build [-o output] [-i] [build flags] [packages] // // Build compiles the packages named by the import paths, // along with their dependencies, but it does not install the results. @@ -94,12 +93,10 @@ // // The -o flag forces build to write the resulting executable or object // to the named output file or directory, instead of the default behavior described -// in the last two paragraphs. If the named output is an existing directory or -// ends with a slash or backslash, then any resulting executables -// will be written to that directory. +// in the last two paragraphs. If the named output is a directory that exists, +// then any resulting executables will be written to that directory. // // The -i flag installs the packages that are dependencies of the target. -// The -i flag is deprecated. Compiled packages are cached automatically. // // The build flags are shared by the build, clean, get, install, list, run, // and test commands: @@ -164,17 +161,6 @@ // directory, but it is not accessed. When -modfile is specified, an // alternate go.sum file is also used: its path is derived from the // -modfile flag by trimming the ".mod" extension and appending ".sum". -// -overlay file -// read a JSON config file that provides an overlay for build operations. -// The file is a JSON struct with a single field, named 'Replace', that -// maps each disk file path (a string) to its backing file path, so that -// a build will run as if the disk file path exists with the contents -// given by the backing file paths, or as if the disk file path does not -// exist if its backing file path is empty. Support for the -overlay flag -// has some limitations:importantly, cgo files included from outside the -// include path must be in the same directory as the Go package they are -// included from, and overlays will not appear when binaries and tests are -// run through go run and go test respectively. // -pkgdir dir // install and load all packages from dir instead of the usual locations. // For example, when building with a non-standard configuration, @@ -630,15 +616,15 @@ // dependency should be removed entirely, downgrading or removing modules // depending on it as needed. // -// The version suffix @latest explicitly requests the latest minor release of -// the module named by the given path. The suffix @upgrade is like @latest but +// The version suffix @latest explicitly requests the latest minor release of the +// module named by the given path. The suffix @upgrade is like @latest but // will not downgrade a module if it is already required at a revision or // pre-release version newer than the latest released version. The suffix // @patch requests the latest patch release: the latest released version // with the same major and minor version numbers as the currently required // version. Like @upgrade, @patch will not downgrade a module already required -// at a newer version. If the path is not already required, @upgrade is -// equivalent to @latest, and @patch is disallowed. +// at a newer version. If the path is not already required, @upgrade and @patch +// are equivalent to @latest. // // Although get defaults to using the latest version of the module containing // a named package, it does not use the latest version of that module's @@ -675,27 +661,14 @@ // this automatically as well. // // The -insecure flag permits fetching from repositories and resolving -// custom domains using insecure schemes such as HTTP, and also bypassess -// module sum validation using the checksum database. Use with caution. -// This flag is deprecated and will be removed in a future version of go. -// To permit the use of insecure schemes, use the GOINSECURE environment -// variable instead. To bypass module sum validation, use GOPRIVATE or -// GONOSUMDB. See 'go help environment' for details. +// custom domains using insecure schemes such as HTTP. Use with caution. The +// GOINSECURE environment variable is usually a better alternative, since it +// provides control over which modules may be retrieved using an insecure scheme. +// See 'go help environment' for details. // // The second step is to download (if needed), build, and install // the named packages. // -// The -d flag instructs get to skip this step, downloading source code -// needed to build the named packages and their dependencies, but not -// building or installing. -// -// Building and installing packages with get is deprecated. In a future release, -// the -d flag will be enabled by default, and 'go get' will be only be used to -// adjust dependencies of the current module. To install a package using -// dependencies from the current module, use 'go install'. To install a package -// ignoring the current module, use 'go install' with an @version suffix like -// "@latest" after each argument. -// // If an argument names a module but not a package (because there is no // Go source code in the module's root directory), then the install step // is skipped for that argument, instead of causing a build failure. @@ -707,6 +680,10 @@ // adds the latest golang.org/x/perf and then installs the commands in that // latest version. // +// The -d flag instructs get to download the source code needed to build +// the named packages, including downloading necessary dependencies, +// but not to build and install them. +// // With no package arguments, 'go get' applies to Go package in the // current directory, if any. In particular, 'go get -u' and // 'go get -u=patch' update all the dependencies of that package. @@ -729,7 +706,7 @@ // // Usage: // -// go install [build flags] [packages] +// go install [-i] [build flags] [packages] // // Install compiles and installs the packages named by the import paths. // @@ -738,39 +715,11 @@ // environment variable is not set. Executables in $GOROOT // are installed in $GOROOT/bin or $GOTOOLDIR instead of $GOBIN. // -// If the arguments have version suffixes (like @latest or @v1.0.0), "go install" -// builds packages in module-aware mode, ignoring the go.mod file in the current -// directory or any parent directory, if there is one. This is useful for -// installing executables without affecting the dependencies of the main module. -// To eliminate ambiguity about which module versions are used in the build, the -// arguments must satisfy the following constraints: -// -// - Arguments must be package paths or package patterns (with "..." wildcards). -// They must not be standard packages (like fmt), meta-patterns (std, cmd, -// all), or relative or absolute file paths. -// - All arguments must have the same version suffix. Different queries are not -// allowed, even if they refer to the same version. -// - All arguments must refer to packages in the same module at the same version. -// - No module is considered the "main" module. If the module containing -// packages named on the command line has a go.mod file, it must not contain -// directives (replace and exclude) that would cause it to be interpreted -// differently than if it were the main module. The module must not require -// a higher version of itself. -// - Package path arguments must refer to main packages. Pattern arguments -// will only match main packages. -// -// If the arguments don't have version suffixes, "go install" may run in -// module-aware mode or GOPATH mode, depending on the GO111MODULE environment -// variable and the presence of a go.mod file. See 'go help modules' for details. -// If module-aware mode is enabled, "go install" runs in the context of the main -// module. -// // When module-aware mode is disabled, other packages are installed in the // directory $GOPATH/pkg/$GOOS_$GOARCH. When module-aware mode is enabled, // other packages are built and cached but not installed. // // The -i flag installs the dependencies of the named packages as well. -// The -i flag is deprecated. Compiled packages are cached automatically. // // For more about the build flags, see 'go help build'. // For more about specifying packages, see 'go help packages'. @@ -817,28 +766,26 @@ // BinaryOnly bool // binary-only package (no longer supported) // ForTest string // package is only for use in named test // Export string // file containing export data (when using -export) -// BuildID string // build ID of the compiled package (when using -export) // Module *Module // info about package's containing module, if any (can be nil) // Match []string // command-line patterns matching this package // DepOnly bool // package is only a dependency, not explicitly listed // // // Source files -// GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) -// CgoFiles []string // .go source files that import "C" -// CompiledGoFiles []string // .go files presented to compiler (when using -compiled) -// IgnoredGoFiles []string // .go source files ignored due to build constraints -// IgnoredOtherFiles []string // non-.go source files ignored due to build constraints -// CFiles []string // .c source files -// CXXFiles []string // .cc, .cxx and .cpp source files -// MFiles []string // .m source files -// HFiles []string // .h, .hh, .hpp and .hxx source files -// FFiles []string // .f, .F, .for and .f90 Fortran source files -// SFiles []string // .s source files -// SwigFiles []string // .swig files -// SwigCXXFiles []string // .swigcxx files -// SysoFiles []string // .syso object files to add to archive -// TestGoFiles []string // _test.go files in package -// XTestGoFiles []string // _test.go files outside package +// GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) +// CgoFiles []string // .go source files that import "C" +// CompiledGoFiles []string // .go files presented to compiler (when using -compiled) +// IgnoredGoFiles []string // .go source files ignored due to build constraints +// CFiles []string // .c source files +// CXXFiles []string // .cc, .cxx and .cpp source files +// MFiles []string // .m source files +// HFiles []string // .h, .hh, .hpp and .hxx source files +// FFiles []string // .f, .F, .for and .f90 Fortran source files +// SFiles []string // .s source files +// SwigFiles []string // .swig files +// SwigCXXFiles []string // .swigcxx files +// SysoFiles []string // .syso object files to add to archive +// TestGoFiles []string // _test.go files in package +// XTestGoFiles []string // _test.go files outside package // // // Cgo directives // CgoCFLAGS []string // cgo: flags for C compiler @@ -969,7 +916,6 @@ // Dir string // directory holding files for this module, if any // GoMod string // path to go.mod file used when loading this module, if any // GoVersion string // go version used in module -// Retracted string // retraction information, if any (with -retracted or -u) // Error *ModuleError // error loading module // } // @@ -1001,16 +947,14 @@ // The -u flag adds information about available upgrades. // When the latest version of a given module is newer than // the current one, list -u sets the Module's Update field -// to information about the newer module. list -u will also set -// the module's Retracted field if the current version is retracted. +// to information about the newer module. // The Module's String method indicates an available upgrade by // formatting the newer version in brackets after the current version. -// If a version is retracted, the string "(retracted)" will follow it. // For example, 'go list -m -u all' might print: // // my/main/module // golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text -// rsc.io/pdf v0.1.1 (retracted) [v0.1.2] +// rsc.io/pdf v0.1.1 [v0.1.2] // // (For tools, 'go list -m -u -json all' may be more convenient to parse.) // @@ -1020,14 +964,6 @@ // the default output format to display the module path followed by the // space-separated version list. // -// The -retracted flag causes list to report information about retracted -// module versions. When -retracted is used with -f or -json, the Retracted -// field will be set to a string explaining why the version was retracted. -// The string is taken from comments on the retract directive in the -// module's go.mod file. When -retracted is used with -versions, retracted -// versions are listed together with unretracted versions. The -retracted -// flag may be used with or without -m. -// // The arguments to list -m are interpreted as a list of modules, not packages. // The main module is the module containing the current directory. // The active modules are the main module and its dependencies. @@ -1164,14 +1100,9 @@ // module path and version pair. If the @v is omitted, a replacement without // a version on the left side is dropped. // -// The -retract=version and -dropretract=version flags add and drop a -// retraction on the given version. The version may be a single version -// like "v1.2.3" or a closed interval like "[v1.1.0,v1.1.9]". Note that -// -retract=version is a no-op if that retraction already exists. -// // The -require, -droprequire, -exclude, -dropexclude, -replace, -// -dropreplace, -retract, and -dropretract editing flags may be repeated, -// and the changes are applied in the order given. +// and -dropreplace editing flags may be repeated, and the changes +// are applied in the order given. // // The -go=version flag sets the expected Go language version. // @@ -1192,7 +1123,6 @@ // Require []Require // Exclude []Module // Replace []Replace -// Retract []Retract // } // // type Require struct { @@ -1206,15 +1136,6 @@ // New Module // } // -// type Retract struct { -// Low string -// High string -// Rationale string -// } -// -// Retract entries representing a single version (not an interval) will have -// the "Low" and "High" fields set to the same value. -// // Note that this only describes the go.mod file itself, not other modules // referred to indirectly. For the full set of modules available to a build, // use 'go list -m -json all'. @@ -1242,24 +1163,19 @@ // // go mod init [module] // -// Init initializes and writes a new go.mod file in the current directory, in -// effect creating a new module rooted at the current directory. The go.mod file -// must not already exist. -// -// Init accepts one optional argument, the module path for the new module. If the -// module path argument is omitted, init will attempt to infer the module path -// using import comments in .go files, vendoring tool configuration files (like -// Gopkg.lock), and the current directory (if in GOPATH). -// -// If a configuration file for a vendoring tool is present, init will attempt to -// import module requirements from it. +// Init initializes and writes a new go.mod to the current directory, +// in effect creating a new module rooted at the current directory. +// The file go.mod must not already exist. +// If possible, init will guess the module path from import comments +// (see 'go help importpath') or from version control configuration. +// To override this guess, supply the module path as an argument. // // // Add missing and remove unused modules // // Usage: // -// go mod tidy [-e] [-v] +// go mod tidy [-v] // // Tidy makes sure go.mod matches the source code in the module. // It adds any missing modules necessary to build the current module's @@ -1270,15 +1186,12 @@ // The -v flag causes tidy to print information about removed modules // to standard error. // -// The -e flag causes tidy to attempt to proceed despite errors -// encountered while loading packages. -// // // Make vendored copy of dependencies // // Usage: // -// go mod vendor [-e] [-v] +// go mod vendor [-v] // // Vendor resets the main module's vendor directory to include all packages // needed to build and test all the main module's packages. @@ -1287,9 +1200,6 @@ // The -v flag causes vendor to print the names of vendored // modules and packages to standard error. // -// The -e flag causes vendor to attempt to proceed despite errors -// encountered while loading packages. -// // // Verify dependencies have expected content // @@ -1478,7 +1388,6 @@ // -i // Install packages that are dependencies of the test. // Do not run the test. -// The -i flag is deprecated. Compiled packages are cached automatically. // // -json // Convert test output to JSON suitable for automated processing. @@ -1637,9 +1546,6 @@ // Using GOOS=illumos matches build tags and files as for GOOS=solaris // in addition to illumos tags and files. // -// Using GOOS=ios matches build tags and files as for GOOS=darwin -// in addition to ios tags and files. -// // To keep a file from being considered for the build: // // // +build ignore @@ -1827,7 +1733,7 @@ // Comma-separated list of glob patterns (in the syntax of Go's path.Match) // of module path prefixes that should always be fetched directly // or that should not be compared against the checksum database. -// See 'go help private'. +// See 'go help module-private'. // GOROOT // The root of the go tree. // GOSUMDB @@ -1883,8 +1789,8 @@ // For GOARCH=arm, the ARM architecture for which to compile. // Valid values are 5, 6, 7. // GO386 -// For GOARCH=386, how to implement floating point instructions. -// Valid values are sse2 (default), softfloat. +// For GOARCH=386, the floating point instruction set. +// Valid values are 387, sse2. // GOMIPS // For GOARCH=mips{,le}, whether to use floating point instructions. // Valid values are hardfloat (default), softfloat. @@ -1933,8 +1839,6 @@ // If module-aware mode is disabled, GOMOD will be the empty string. // GOTOOLDIR // The directory where the go tools (compile, cover, doc, etc...) are installed. -// GOVERSION -// The version of the installed Go tree, as reported by runtime.Version. // // // File types @@ -1990,23 +1894,21 @@ // require new/thing/v2 v2.3.4 // exclude old/thing v1.2.3 // replace bad/thing v1.4.5 => good/thing v1.4.5 -// retract v1.5.6 // // The verbs are // module, to define the module path; // go, to set the expected language version; // require, to require a particular module at a given version or later; -// exclude, to exclude a particular module version from use; -// replace, to replace a module version with a different module version; and -// retract, to indicate a previously released version should not be used. +// exclude, to exclude a particular module version from use; and +// replace, to replace a module version with a different module version. // Exclude and replace apply only in the main module's go.mod and are ignored -// in dependencies. See https://golang.org/ref/mod for details. +// in dependencies. See https://research.swtch.com/vgo-mvs for details. // // The leading verb can be factored out of adjacent lines to create a block, // like in Go imports: // // require ( -// new/thing/v2 v2.3.4 +// new/thing v2.3.4 // old/thing v1.2.3 // ) // @@ -2244,10 +2146,6 @@ // // The -insecure flag permits fetching from repositories and resolving // custom domains using insecure schemes such as HTTP. Use with caution. -// This flag is deprecated and will be removed in a future version of go. -// The GOINSECURE environment variable should be used instead, since it -// provides control over which packages may be retrieved using an insecure -// scheme. See 'go help environment' for details. // // The -t flag instructs get to also download the packages required to build // the tests for the specified packages. @@ -2658,63 +2556,72 @@ // // Maintaining module requirements // -// The go.mod file is meant to be readable and editable by both programmers and -// tools. Most updates to dependencies can be performed using "go get" and -// "go mod tidy". Other module-aware build commands may be invoked using the -// -mod=mod flag to automatically add missing requirements and fix inconsistencies. -// -// The "go get" command updates go.mod to change the module versions used in a -// build. An upgrade of one module may imply upgrading others, and similarly a -// downgrade of one module may imply downgrading others. The "go get" command -// makes these implied changes as well. See "go help module-get". -// -// The "go mod" command provides other functionality for use in maintaining -// and understanding modules and go.mod files. See "go help mod", particularly -// "go help mod tidy" and "go help mod edit". +// The go.mod file is meant to be readable and editable by both +// programmers and tools. The go command itself automatically updates the go.mod file +// to maintain a standard formatting and the accuracy of require statements. +// +// Any go command that finds an unfamiliar import will look up the module +// containing that import and add the latest version of that module +// to go.mod automatically. In most cases, therefore, it suffices to +// add an import to source code and run 'go build', 'go test', or even 'go list': +// as part of analyzing the package, the go command will discover +// and resolve the import and update the go.mod file. +// +// Any go command can determine that a module requirement is +// missing and must be added, even when considering only a single +// package from the module. On the other hand, determining that a module requirement +// is no longer necessary and can be deleted requires a full view of +// all packages in the module, across all possible build configurations +// (architectures, operating systems, build tags, and so on). +// The 'go mod tidy' command builds that view and then +// adds any missing module requirements and removes unnecessary ones. // // As part of maintaining the require statements in go.mod, the go command // tracks which ones provide packages imported directly by the current module // and which ones provide packages only used indirectly by other module // dependencies. Requirements needed only for indirect uses are marked with a -// "// indirect" comment in the go.mod file. Indirect requirements may be +// "// indirect" comment in the go.mod file. Indirect requirements are // automatically removed from the go.mod file once they are implied by other // direct requirements. Indirect requirements only arise when using modules // that fail to state some of their own dependencies or when explicitly // upgrading a module's dependencies ahead of its own stated requirements. // -// The -mod build flag provides additional control over the updating and use of -// go.mod for commands that build packages like "go build" and "go test". -// -// If invoked with -mod=readonly (the default in most situations), the go command -// reports an error if a package named on the command line or an imported package -// is not provided by any module in the build list computed from the main module's -// requirements. The go command also reports an error if a module's checksum is -// missing from go.sum (see Module downloading and verification). Either go.mod or -// go.sum must be updated in these situations. -// -// If invoked with -mod=mod, the go command automatically updates go.mod and -// go.sum, fixing inconsistencies and adding missing requirements and checksums -// as needed. If the go command finds an unfamiliar import, it looks up the -// module containing that import and adds a requirement for the latest version -// of that module to go.mod. In most cases, therefore, one may add an import to -// source code and run "go build", "go test", or even "go list" with -mod=mod: -// as part of analyzing the package, the go command will resolve the import and -// update the go.mod file. +// Because of this automatic maintenance, the information in go.mod is an +// up-to-date, readable description of the build. +// +// The 'go get' command updates go.mod to change the module versions used in a +// build. An upgrade of one module may imply upgrading others, and similarly a +// downgrade of one module may imply downgrading others. The 'go get' command +// makes these implied changes as well. If go.mod is edited directly, commands +// like 'go build' or 'go list' will assume that an upgrade is intended and +// automatically make any implied upgrades and update go.mod to reflect them. +// +// The 'go mod' command provides other functionality for use in maintaining +// and understanding modules and go.mod files. See 'go help mod'. +// +// The -mod build flag provides additional control over updating and use of go.mod. +// +// If invoked with -mod=readonly, the go command is disallowed from the implicit +// automatic updating of go.mod described above. Instead, it fails when any changes +// to go.mod are needed. This setting is most useful to check that go.mod does +// not need updates, such as in a continuous integration and testing system. +// The "go get" command remains permitted to update go.mod even with -mod=readonly, +// and the "go mod" commands do not take the -mod flag (or any other build flags). // // If invoked with -mod=vendor, the go command loads packages from the main // module's vendor directory instead of downloading modules to and loading packages // from the module cache. The go command assumes the vendor directory holds // correct copies of dependencies, and it does not compute the set of required // module versions from go.mod files. However, the go command does check that -// vendor/modules.txt (generated by "go mod vendor") contains metadata consistent +// vendor/modules.txt (generated by 'go mod vendor') contains metadata consistent // with go.mod. // -// If the go command is not invoked with a -mod flag, and the vendor directory -// is present, and the "go" version in go.mod is 1.14 or higher, the go command -// will act as if it were invoked with -mod=vendor. Otherwise, the -mod flag -// defaults to -mod=readonly. +// If invoked with -mod=mod, the go command loads modules from the module cache +// even if there is a vendor directory present. // -// Note that neither "go get" nor the "go mod" subcommands accept the -mod flag. +// If the go command is not invoked with a -mod flag and the vendor directory +// is present and the "go" version in go.mod is 1.14 or higher, the go command +// will act as if it were invoked with -mod=vendor. // // Pseudo-versions // @@ -2899,7 +2806,7 @@ // followed by a pipe character, indicating it is safe to fall back on any error. // // The GOPRIVATE and GONOPROXY environment variables allow bypassing -// the proxy for selected modules. See 'go help private' for details. +// 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 @@ -3019,7 +2926,52 @@ // 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. +// 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 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, +// +// 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 +// +// 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 'go env -w' command (see 'go help env') can be used to set these variables // for future go command invocations. @@ -3109,56 +3061,6 @@ // by the go tool, as are directories named "testdata". // // -// Configuration for downloading non-public code -// -// 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, -// -// 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 -// -// 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 -// 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. -// -// // Testing flags // // The 'go test' command takes both flags that apply to 'go test' itself @@ -3451,77 +3353,4 @@ // See the documentation of the testing package for more information. // // -// Controlling version control with GOVCS -// -// The 'go get' command can run version control commands like git -// to download imported code. This functionality is critical to the decentralized -// Go package ecosystem, in which code can be imported from any server, -// but it is also a potential security problem, if a malicious server finds a -// way to cause the invoked version control command to run unintended code. -// -// To balance the functionality and security concerns, the 'go get' command -// by default will only use git and hg to download code from public servers. -// But it will use any known version control system (bzr, fossil, git, hg, svn) -// to download code from private servers, defined as those hosting packages -// matching the GOPRIVATE variable (see 'go help private'). The rationale behind -// allowing only Git and Mercurial is that these two systems have had the most -// attention to issues of being run as clients of untrusted servers. In contrast, -// Bazaar, Fossil, and Subversion have primarily been used in trusted, -// authenticated environments and are not as well scrutinized as attack surfaces. -// -// The version control command restrictions only apply when using direct version -// control access to download code. When downloading modules from a proxy, -// 'go get' uses the proxy protocol instead, which is always permitted. -// By default, the 'go get' command uses the Go module mirror (proxy.golang.org) -// for public packages and only falls back to version control for private -// packages or when the mirror refuses to serve a public package (typically for -// legal reasons). Therefore, clients can still access public code served from -// Bazaar, Fossil, or Subversion repositories by default, because those downloads -// use the Go module mirror, which takes on the security risk of running the -// version control commands, using a custom sandbox. -// -// The GOVCS variable can be used to change the allowed version control systems -// for specific packages (identified by a module or import path). -// The GOVCS variable applies both when using modules and when using GOPATH. -// When using modules, the patterns match against the module path. -// When using GOPATH, the patterns match against the import path -// corresponding to the root of the version control repository. -// -// The general form of the GOVCS setting is a comma-separated list of -// pattern:vcslist rules. The pattern is a glob pattern that must match -// one or more leading elements of the module or import path. The vcslist -// is a pipe-separated list of allowed version control commands, or "all" -// to allow use of any known command, or "off" to allow nothing. -// The earliest matching pattern in the list applies, even if later patterns -// might also match. -// -// For example, consider: -// -// GOVCS=github.com:git,evil.com:off,*:git|hg -// -// With this setting, code with an module or import path beginning with -// github.com/ can only use git; paths on evil.com cannot use any version -// control command, and all other paths (* matches everything) can use -// only git or hg. -// -// The special patterns "public" and "private" match public and private -// module or import paths. A path is private if it matches the GOPRIVATE -// variable; otherwise it is public. -// -// If no rules in the GOVCS variable match a particular module or import path, -// the 'go get' command applies its default rule, which can now be summarized -// in GOVCS notation as 'public:git|hg,private:all'. -// -// To allow unfettered use of any version control system for any package, use: -// -// GOVCS=*:all -// -// To disable all use of version control, use: -// -// GOVCS=*:off -// -// The 'go env -w' command (see 'go help env') can be used to set the GOVCS -// variable for future go command invocations. -// -// package main diff --git a/src/cmd/go/internal/help/helpdoc.go b/src/cmd/go/internal/help/helpdoc.go index 98f58441b4de60..fd9212f1f4e2c2 100644 --- a/src/cmd/go/internal/help/helpdoc.go +++ b/src/cmd/go/internal/help/helpdoc.go @@ -535,6 +535,16 @@ General-purpose environment variables: GOTMPDIR The directory where the go command will write temporary source files, packages, and binaries. + GO111MODULE + which can be set to one of three string values: off, on (the default), or auto. + If GO111MODULE=on, then the go command requires the use of modules, + never consulting GOPATH. We refer to this as the command being module-aware + or running in "module-aware mode". + If GO111MODULE=off, then the go command never uses module support. + Instead it looks in vendor directories and GOPATH + to find dependencies; we now refer to this as "GOPATH mode." + If GO111MODULE=auto or is unset, then the go command enables or disables + module support based on the current directory. Environment variables for use with cgo: