From b816cb2cd5f1b7cee660c6e4b85d8130b960752a Mon Sep 17 00:00:00 2001 From: Jay Conrod Date: Wed, 18 Mar 2020 14:59:44 -0400 Subject: [PATCH] cmd/go: update 'go help modules' for automatic vendoring * Mention vendor/modules.txt verification with -mod=vendor. * Update "Modules and vendoring" section. Fixes #37930 Change-Id: Ia3ee72457daabaa2fc15b7ea7427eb324c088b8f Reviewed-on: https://go-review.googlesource.com/c/go/+/223926 Run-TryBot: Jay Conrod Reviewed-by: Bryan C. Mills --- src/cmd/go/alldocs.go | 48 +++++++++++++++++++---------- src/cmd/go/internal/modload/help.go | 48 +++++++++++++++++++---------- 2 files changed, 62 insertions(+), 34 deletions(-) diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index 971a756b37d..c2678c3dd3c 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 66c1f70db73..bd19bb43aa0 100644 --- a/src/cmd/go/internal/modload/help.go +++ b/src/cmd/go/internal/modload/help.go @@ -176,13 +176,21 @@ 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 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 @@ the format of the cached downloaded packages. 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. `, }