[release-branch.go1.14] cmd/go: update 'go help modules' for automatic vendoring
* Mention vendor/modules.txt verification with -mod=vendor.
* Update "Modules and vendoring" section.
Fixes #37931
Change-Id: Ia3ee72457daabaa2fc15b7ea7427eb324c088b8f
Reviewed-on: https://go-review.googlesource.com/c/go/+/223926
Run-TryBot: Jay Conrod <jayconrod@google.com>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
(cherry picked from commit b816cb2cd5f1b7cee660c6e4b85d8130b960752a)
Reviewed-on: https://go-review.googlesource.com/c/go/+/224119
TryBot-Result: Gobot Gobot <gobot@golang.org>
diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 971a756..c2678c3 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -2506,13 +2506,21 @@
// 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 assumes that the vendor
-// directory holds the correct copies of dependencies and ignores
-// the dependency descriptions in go.mod.
+// 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
+// with go.mod.
//
// If invoked with -mod=mod, the go command loads modules from the module cache
// even if there is a vendor directory present.
//
+// 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
//
// The go.mod file and the go command more generally use semantic versions as
@@ -2710,22 +2718,28 @@
//
// Modules and vendoring
//
-// When using modules, the go command completely ignores vendor directories.
+// When using modules, the go command typically satisfies dependencies by
+// downloading modules from their sources and using those downloaded copies
+// (after verification, as described in the previous section). Vendoring may
+// be used to allow interoperation with older versions of Go, or to ensure
+// that all files used for a build are stored together in a single file tree.
//
-// By default, the go command satisfies dependencies by downloading modules
-// from their sources and using those downloaded copies (after verification,
-// as described in the previous section). To allow interoperation with older
-// versions of Go, or to ensure that all files used for a build are stored
-// together in a single file tree, 'go mod vendor' creates a directory named
-// vendor in the root directory of the main module and stores there all the
-// packages from dependency modules that are needed to support builds and
-// tests of packages in the main module.
+// The command 'go mod vendor' constructs a directory named vendor in the main
+// module's root directory that contains copies of all packages needed to support
+// builds and tests of packages in the main module. 'go mod vendor' also
+// creates the file vendor/modules.txt that contains metadata about vendored
+// packages and module versions. This file should be kept consistent with go.mod:
+// when vendoring is used, 'go mod vendor' should be run after go.mod is updated.
//
-// To build using the main module's top-level vendor directory to satisfy
-// dependencies (disabling use of the usual network sources and local
-// caches), use 'go build -mod=vendor'. Note that only the main module's
-// top-level vendor directory is used; vendor directories in other locations
-// are still ignored.
+// If the vendor directory is present in the main module's root directory, it will
+// be used automatically if the "go" version in the main module's go.mod file is
+// 1.14 or higher. Build commands like 'go build' and 'go test' will load packages
+// from the vendor directory instead of accessing the network or the local module
+// cache. To explicitly enable vendoring, invoke the go command with the flag
+// -mod=vendor. To disable vendoring, use the flag -mod=mod.
+//
+// Unlike vendoring in GOPATH, the go command ignores vendor directories in
+// locations other than the main module's root directory.
//
//
// Module authentication using go.sum
diff --git a/src/cmd/go/internal/modload/help.go b/src/cmd/go/internal/modload/help.go
index 66c1f70..bd19bb4 100644
--- a/src/cmd/go/internal/modload/help.go
+++ b/src/cmd/go/internal/modload/help.go
@@ -176,13 +176,21 @@
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 assumes that the vendor
-directory holds the correct copies of dependencies and ignores
-the dependency descriptions in go.mod.
+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
+with go.mod.
If invoked with -mod=mod, the go command loads modules from the module cache
even if there is a vendor directory present.
+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
The go.mod file and the go command more generally use semantic versions as
@@ -380,22 +388,28 @@
Modules and vendoring
-When using modules, the go command completely ignores vendor directories.
+When using modules, the go command typically satisfies dependencies by
+downloading modules from their sources and using those downloaded copies
+(after verification, as described in the previous section). Vendoring may
+be used to allow interoperation with older versions of Go, or to ensure
+that all files used for a build are stored together in a single file tree.
-By default, the go command satisfies dependencies by downloading modules
-from their sources and using those downloaded copies (after verification,
-as described in the previous section). To allow interoperation with older
-versions of Go, or to ensure that all files used for a build are stored
-together in a single file tree, 'go mod vendor' creates a directory named
-vendor in the root directory of the main module and stores there all the
-packages from dependency modules that are needed to support builds and
-tests of packages in the main module.
+The command 'go mod vendor' constructs a directory named vendor in the main
+module's root directory that contains copies of all packages needed to support
+builds and tests of packages in the main module. 'go mod vendor' also
+creates the file vendor/modules.txt that contains metadata about vendored
+packages and module versions. This file should be kept consistent with go.mod:
+when vendoring is used, 'go mod vendor' should be run after go.mod is updated.
-To build using the main module's top-level vendor directory to satisfy
-dependencies (disabling use of the usual network sources and local
-caches), use 'go build -mod=vendor'. Note that only the main module's
-top-level vendor directory is used; vendor directories in other locations
-are still ignored.
+If the vendor directory is present in the main module's root directory, it will
+be used automatically if the "go" version in the main module's go.mod file is
+1.14 or higher. Build commands like 'go build' and 'go test' will load packages
+from the vendor directory instead of accessing the network or the local module
+cache. To explicitly enable vendoring, invoke the go command with the flag
+-mod=vendor. To disable vendoring, use the flag -mod=mod.
+
+Unlike vendoring in GOPATH, the go command ignores vendor directories in
+locations other than the main module's root directory.
`,
}
