// arguments to pass on each gccgo compiler/linker invocation.
// -gcflags '[pattern=]arg list'
// arguments to pass on each go tool compile invocation.
-// -getmode mode
-// module download mode to use. See 'go help modules' for more.
// -installsuffix suffix
// a suffix to use in the name of the package installation directory,
// in order to keep output separate from default builds.
// -linkshared
// link against shared libraries previously created with
// -buildmode=shared.
+// -mod mode
+// module download mode to use: readonly, release, or vendor.
+// See 'go help modules' for more.
// -pkgdir dir
// install and load all packages from dir instead of the usual locations.
// For example, when building with a non-standard configuration,
// Module *Module // info about package's containing module, if any (can be nil)
//
// // Source files
-// GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)
-// CgoFiles []string // .go sources files that import "C"
-// IgnoredGoFiles []string // .go sources 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
// The -json flag causes the package data to be printed in JSON format
// instead of using the template format.
//
-// The -cgo flag causes list to set CgoFiles not to the original *.go files
-// importing "C" but instead to the translated files generated by the cgo
-// command.
+// The -compiled flag causes list to set CompiledGoFiles to the Go source
+// files presented to the compiler. Typically this means that it repeats
+// the files listed in GoFiles and then also adds the Go code generated
+// by processing CgoFiles and SwigFiles.
//
// The -deps flag causes list to iterate over not just the named packages
// but also all their dependencies. It visits them in a depth-first post-order
// The -export flag causes list to set the Export field to the name of a
// file containing up-to-date export information for the given package.
//
+// The -find flag causes list to identify the named packages but not
+// resolve their dependencies: the Imports and Deps lists will be empty.
+//
// The -test flag causes list to report not only the named packages
// but also their test binaries (for packages with tests), to convey to
// source code analysis tools exactly how test binaries are constructed.
//
// By default, the lists GoFiles, CgoFiles, and so on hold names of files in Dir
// (that is, paths relative to Dir, not absolute paths).
-// The extra entries added by the -cgo and -test flags are absolute paths
-// referring to cached copies of generated Go source files.
+// The generated files added when using the -compiled and -test flags
+// are absolute paths referring to cached copies of generated Go source files.
// Although they are Go source files, the paths may not end in ".go".
//
// The -m flag causes list to list modules instead of packages.
//
// The -module flag changes the module's path (the go.mod file's module line).
//
-// The -go flag changes the minimum required version of Go listed in go.mod.
-//
// The -require=path@version and -droprequire=path flags
// add and drop a requirement on the given module path and version.
// Note that -require overrides any existing requirements on path.
// add and drop an exclusion for the given module path and version.
// Note that -exclude=path@version is a no-op if that exclusion already exists.
//
-// The -replace=old@v=new@w and -dropreplace=old@v flags
+// The -replace=old[@v]=new[@v] and -dropreplace=old[@v] flags
// add and drop a replacement of the given module path and version pair.
// If the @v in old@v is omitted, the replacement applies to all versions
-// with the old module path. If the @v in new@v is omitted, the
-// new path should be a directory on the local system, not a module path.
-// Note that -replace overrides any existing replacements for old@v.
+// with the old module path. If the @v in new@v is omitted, the new path
+// should be a local module root directory, not a module path.
+// Note that -replace overrides any existing replacements for old[@v].
//
// The -require, -droprequire, -exclude, -dropexclude, -replace,
// and -dropreplace editing flags may be repeated, and the changes
// perhaps D v1.2.4 or D v1.3.0.
//
// Finally, fix removes redundant or misleading requirements.
-// For example, if A v1.0.0 itself requires B v1.2.0 and C v1.0.0,
-// then go.mod's requirement of B v1.0.0 is misleading (superseded
-// by B's need for v1.2.0), and its requirement of C v1.0.0 is redundant
-// (implied by B's need for the same version), so both will be removed.
+// For example, if A v1.0.0 itself requires B v1.2.0 and C v1.0.0, then go.mod's
+// requirement of B v1.0.0 is misleading (superseded by A's need for v1.2.0),
+// and its requirement of C v1.0.0 is redundant (implied by A's need for the
+// same version), so both will be removed. If module M contains packages
+// that directly import packages from B or C, then the requirements will be
+// kept but updated to the actual versions being used.
//
// Although fix runs the fix-up operation in isolation, the fix-up also
// runs automatically any time a go command uses the module graph,
// information for reuse in future builds.
// GOFLAGS
// A space-separated list of -flag=value settings to apply
-// to go commands by default (when the given flag is known by
-// the current command).
+// to go commands by default, when the given flag is known by
+// the current command. Flags listed on the command-line
+// are applied after this list and therefore override it.
// GOOS
// The operating system for which to compile code.
// Examples are linux, darwin, windows, netbsd.
// GOPATH and Modules
//
// When using modules, GOPATH is no longer used for resolving imports.
-// However, it is still used to store downloaded source code (in GOPATH/src/mod)
+// However, it is still used to store downloaded source code (in GOPATH/pkg/mod)
// and compiled commands (in GOPATH/bin).
//
// Internal Directories
// Module proxy protocol
//
// The go command by default downloads modules from version control systems
-// directly, just as 'go get' always has. If the GOPROXY environment variable
-// is set to the URL of a module proxy, the go command will instead fetch
-// all modules from that proxy. No matter the source of the modules, downloaded
-// modules must match existing entries in go.sum (see 'go help modules' for
-// discussion of verification).
+// directly, just as 'go get' always has. The GOPROXY environment variable allows
+// further control over the download source. GOPROXY being unset, the empty string,
+// or the string "direct" corresponds to the default direct connection to version
+// control systems. Setting GOPROXY to "off" disallows downloading modules from
+// any source. Otherwise, if GOPROXY is expected to be the URL of a module proxy,
+// in which case the go command will fetch all modules from that proxy.
+// No matter the source of the modules, downloaded modules must match existing
+// entries in go.sum (see 'go help modules' for discussion of verification).
//
// A Go module proxy is any web server that can respond to GET requests for
// URLs of a specified form. The requests have no query parameters, so even
//
// Even when downloading directly from version control systems,
// the go command synthesizes explicit info, mod, and zip files
-// and stores them in its local cache, $GOPATH/src/mod/cache/download,
+// and stores them in its local cache, $GOPATH/pkg/mod/cache/download,
// the same as if it had downloaded them directly from a proxy.
// The cache layout is the same as the proxy URL space, so
-// serving $GOPATH/src/mod/cache/download at (or copying it to)
+// serving $GOPATH/pkg/mod/cache/download at (or copying it to)
// https://example.com/proxy would let other users access those
// cached module versions with GOPROXY=https://example.com/proxy.
//
// Modules replace the old GOPATH-based approach to specifying
// which source files are used in a given build.
//
-// Experimental module support
+// Preliminary module support
//
-// Go 1.11 includes experimental support for Go modules,
+// Go 1.11 includes preliminary support for Go modules,
// including a new module-aware 'go get' command.
// We intend to keep revising this support, while preserving compatibility,
-// until it can be declared official (no longer experimental),
+// until it can be declared official (no longer preliminary),
// and then at a later point we may remove support for work
// in GOPATH and the old 'go get' command.
//
// containing a go.mod file.
//
// In module-aware mode, GOPATH no longer defines the meaning of imports
-// during a build, but it still stores downloaded dependencies (in GOPATH/src/mod)
+// during a build, but it still stores downloaded dependencies (in GOPATH/pkg/mod)
// and installed commands (in GOPATH/bin, unless GOBIN is set).
//
// Defining a module
// 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 disables its automatic updates
+// of go.mod as described above and fails if any changes are needed. This setting
+// is most useful to check that go.mod does not need any updates, such as in a
+// continuous integration and testing system.
+// 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.
+//
// Pseudo-versions
//
// The go.mod file and the go command more generally use semantic versions as
//
// 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 -getmode=vendor'. Note that only the main module's
+// 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.
//