cmd/go: generate alldocs.go

Change-Id: I5a82aec66332f52e304f647758221b5f30b4e2b6
Reviewed-on: https://go-review.googlesource.com/124701
Reviewed-by: Bryan C. Mills <bcmills@google.com>

src/cmd/go/alldocs.go

@@ -23,7 +23,8 @@
 // 	generate    generate Go files by processing source
 // 	get         download and install packages and dependencies
 // 	install     compile and install packages and dependencies
-// 	list        list packages
+// 	list        list packages or modules
+// 	mod         module maintenance
 // 	run         compile and run Go program
 // 	test        test packages
 // 	tool        run specified go tool
@@ -40,8 +41,11 @@
 // 	environment environment variables
 // 	filetype    file types
 // 	gopath      GOPATH environment variable
+// 	gopath-get  legacy GOPATH go get
 // 	importpath  import path syntax
-// 	packages    package lists
+// 	modules     modules, module versions, and more
+// 	module-get  module-aware go get
+// 	packages    package lists and patterns
 // 	testflag    testing flags
 // 	testfunc    testing functions
 //
@@ -125,6 +129,8 @@
 // 		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.
@@ -185,7 +191,7 @@
 //
 // Usage:
 //
-// 	go clean [-i] [-r] [-n] [-x] [-cache] [-testcache] [build flags] [packages]
+// 	go clean [clean flags] [build flags] [packages]
 //
 // Clean removes object files from package source directories.
 // The go command builds most objects in a temporary directory,
@@ -228,6 +234,10 @@
 // The -testcache flag causes clean to expire all test results in the
 // go build cache.
 //
+// The -modcache flag causes clean to remove the entire module
+// download cache, including unpacked source code of versioned
+// dependencies.
+//
 // For more about build flags, see 'go help build'.
 //
 // For more about specifying packages, see 'go help packages'.
@@ -512,7 +522,7 @@
 //
 // Usage:
 //
-// 	go get [-d] [-f] [-fix] [-insecure] [-t] [-u] [-v] [build flags] [packages]
+// 	go get [-d] [-f] [-t] [-u] [-v] [-fix] [-insecure] [build flags] [packages]
 //
 // Get downloads the packages named by the import paths, along with their
 // dependencies. It then installs the named packages, like 'go install'.
@@ -562,6 +572,12 @@
 // For more about how 'go get' finds source code to
 // download, see 'go help importpath'.
 //
+// This text describes the behavior of get when using GOPATH
+// to manage source code and dependencies.
+// If instead the go command is running in module-aware mode,
+// the details of get's flags and effects change, as does 'go help get'.
+// See 'go help modules' and 'go help module-get'.
+//
 // See also: go build, go install, go clean.
 //
 //
@@ -581,13 +597,16 @@
 // See also: go build, go get, go clean.
 //
 //
-// List packages
+// List packages or modules
 //
 // Usage:
 //
-// 	go list [-cgo] [-deps] [-e] [-export] [-f format] [-json] [-test] [build flags] [packages]
+// 	go list [-f format] [-json] [-m] [list flags] [build flags] [packages]
 //
-// List lists the packages named by the import paths, one per line.
+// List lists the named packages, one per line.
+// The most commonly-used flags are -f and -json, which control the form
+// of the output printed for each package. Other list flags, documented below,
+// control more specific details.
 //
 // The default output shows the package import path:
 //
@@ -597,27 +616,28 @@
 //     golang.org/x/net/html
 //
 // The -f flag specifies an alternate format for the list, using the
-// syntax of package template. The default output is equivalent to -f
+// syntax of package template. The default output is equivalent
-// '{{.ImportPath}}'. The struct being passed to the template is:
+// to -f '{{.ImportPath}}'. The struct being passed to the template is:
 //
 //     type Package struct {
-//         Dir           string // directory containing package sources
+//         Dir           string  // directory containing package sources
-//         ImportPath    string // import path of package in dir
+//         ImportPath    string  // import path of package in dir
-//         ImportComment string // path in import comment on package statement
+//         ImportComment string  // path in import comment on package statement
-//         Name          string // package name
+//         Name          string  // package name
-//         Doc           string // package documentation string
+//         Doc           string  // package documentation string
-//         Target        string // install path
+//         Target        string  // install path
-//         Shlib         string // the shared library that contains this package (only set when -linkshared)
+//         Shlib         string  // the shared library that contains this package (only set when -linkshared)
-//         Goroot        bool   // is this package in the Go root?
+//         Goroot        bool    // is this package in the Go root?
-//         Standard      bool   // is this package part of the standard Go library?
+//         Standard      bool    // is this package part of the standard Go library?
-//         Stale         bool   // would 'go install' do anything for this package?
+//         Stale         bool    // would 'go install' do anything for this package?
-//         StaleReason   string // explanation for Stale==true
+//         StaleReason   string  // explanation for Stale==true
-//         Root          string // Go root or Go path dir containing this package
+//         Root          string  // Go root or Go path dir containing this package
-//         ConflictDir   string // this directory shadows Dir in $GOPATH
+//         ConflictDir   string  // this directory shadows Dir in $GOPATH
-//         BinaryOnly    bool   // binary-only package: cannot be recompiled from sources
+//         BinaryOnly    bool    // binary-only package: cannot be recompiled from sources
-//         ForTest       string // package is only for use in named test
+//         ForTest       string  // package is only for use in named test
-//         DepOnly       bool   // package is only a dependency, not explicitly listed
+//         DepOnly       bool    // package is only a dependency, not explicitly listed
-//         Export        string // file containing export data (when using -export)
+//         Export        string  // file containing export data (when using -export)
+//         Module        *Module // info about package's containing module, if any (can be nil)
 //
 //         // Source files
 //         GoFiles        []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)
@@ -644,10 +664,11 @@
 //         CgoPkgConfig []string // cgo: pkg-config names
 //
 //         // Dependency information
-//         Imports      []string // import paths used by this package
+//         Imports      []string          // import paths used by this package
-//         Deps         []string // all (recursively) imported dependencies
+//         ImportMap    map[string]string // map from source import to ImportPath (identity entries omitted)
-//         TestImports  []string // imports from TestGoFiles
+//         Deps         []string          // all (recursively) imported dependencies
-//         XTestImports []string // imports from XTestGoFiles
+//         TestImports  []string          // imports from TestGoFiles
+//         XTestImports []string          // imports from XTestGoFiles
 //
 //         // Error information
 //         Incomplete bool            // this package or a dependency has an error
@@ -669,22 +690,25 @@
 //         Err           string   // the error itself
 //     }
 //
+// The module information is a Module struct, defined in the discussion
+// of list -m below.
+//
 // The template function "join" calls strings.Join.
 //
 // The template function "context" returns the build context, defined as:
 //
-// 	type Context struct {
+//     type Context struct {
-// 		GOARCH        string   // target architecture
+//         GOARCH        string   // target architecture
-// 		GOOS          string   // target operating system
+//         GOOS          string   // target operating system
-// 		GOROOT        string   // Go root
+//         GOROOT        string   // Go root
-// 		GOPATH        string   // Go path
+//         GOPATH        string   // Go path
-// 		CgoEnabled    bool     // whether cgo can be used
+//         CgoEnabled    bool     // whether cgo can be used
-// 		UseAllFiles   bool     // use files regardless of +build lines, file names
+//         UseAllFiles   bool     // use files regardless of +build lines, file names
-// 		Compiler      string   // compiler to assume when computing target paths
+//         Compiler      string   // compiler to assume when computing target paths
-// 		BuildTags     []string // build constraints to match in +build lines
+//         BuildTags     []string // build constraints to match in +build lines
-// 		ReleaseTags   []string // releases the current release is compatible with
+//         ReleaseTags   []string // releases the current release is compatible with
-// 		InstallSuffix string   // suffix to use in the name of the install dir
+//         InstallSuffix string   // suffix to use in the name of the install dir
-// 	}
+//     }
 //
 // For more information about the meaning of these fields see the documentation
 // for the go/build package's Context type.
@@ -738,10 +762,242 @@
 // 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.
+//
+// When listing modules, the -f flag still specifies a format template
+// applied to a Go struct, but now a Module struct:
+//
+//     type Module struct {
+//         Path     string       // module path
+//         Version  string       // module version
+//         Versions []string     // available module versions (with -versions)
+//         Replace  *Module      // replaced by this module
+//         Time     *time.Time   // time version was created
+//         Update   *Module      // available update, if any (with -u)
+//         Main     bool         // is this the main module?
+//         Indirect bool         // is this module only an indirect dependency of main module?
+//         Dir      string       // directory holding files for this module, if any
+//         Error    *ModuleError // error loading module
+//     }
+//
+//     type ModuleError struct {
+//         Err string // the error itself
+//     }
+//
+// The default output is to print the module path and then
+// information about the version and replacement if any.
+// For example, 'go list -m all' might print:
+//
+//     my/main/module
+//     golang.org/x/text v0.3.0 => /tmp/text
+//     rsc.io/pdf v0.1.1
+//
+// The Module struct has a String method that formats this
+// line of output, so that the default format is equivalent
+// to -f '{{.String}}'.
+//
+// Note that when a module has been replaced, its Replace field
+// describes the replacement module, and its Dir field is set to
+// the replacement's source code, if present. (That is, if Replace
+// is non-nil, then Dir is set to Replace.Dir, with no access to
+// the replaced source code.)
+//
+// 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.
+// The Module's String method indicates an available upgrade by
+// formatting the newer version in brackets after the current version.
+// 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 [v0.1.2]
+//
+// (For tools, 'go list -m -u -json all' may be more convenient to parse.)
+//
+// The -versions flag causes list to set the Module's Versions field
+// to a list of all known versions of that module, ordered according
+// to semantic versioning, earliest to latest. The flag also changes
+// the default output format to display the module path followed by the
+// space-separated version list.
+//
+// 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.
+// With no arguments, list -m shows the main module.
+// With arguments, list -m shows the modules specified by the arguments.
+// Any of the active modules can be specified by its module path.
+// The special pattern "all" specifies all the active modules, first the main
+// module and then dependencies sorted by module path.
+// A pattern containing "..." specifies the active modules whose
+// module paths match the pattern.
+// A query of the form path@version specifies the result of that query,
+// which is not limited to active modules.
+// See 'go help module' for more about module queries.
+//
+// The template function "module" takes a single string argument
+// that must be a module path or query and returns the specified
+// module as a Module struct. If an error occurs, the result will
+// be a Module struct with a non-nil Error field.
+//
 // For more about build flags, see 'go help build'.
 //
 // For more about specifying packages, see 'go help packages'.
 //
+// For more about modules, see 'go help modules'.
+//
+//
+// Module maintenance
+//
+// Usage:
+//
+// 	go mod [-v] [maintenance flags]
+//
+// Mod performs module maintenance operations as specified by the
+// following flags, which may be combined.
+//
+// The -v flag enables additional output about operations performed.
+//
+// The first group of operations provide low-level editing operations
+// for manipulating go.mod from the command line or in scripts or
+// other tools. They read only go.mod itself; they do not look up any
+// information about the modules involved.
+//
+// The -init flag 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, mod will guess the module path from import comments
+// (see 'go help importpath') or from version control configuration.
+// To override this guess, use the -module flag.
+// (Without -init, mod applies to the current module.)
+//
+// The -module flag changes (or, with -init, sets) the module's path
+// (the go.mod file's module line).
+//
+// 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.
+// These flags are mainly for tools that understand the module graph.
+// Users should prefer 'go get path@version' or 'go get path@none',
+// which make other go.mod adjustments as needed to satisfy
+// constraints imposed by other modules.
+//
+// The -exclude=path@version and -dropexclude=path@version flags
+// 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
+// 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.
+//
+// These editing flags (-require, -droprequire, -exclude, -dropexclude,
+// -replace, and -dropreplace) may be repeated.
+//
+// The -fmt flag reformats the go.mod file without making other changes.
+// This reformatting is also implied by any other modifications that use or
+// rewrite the go.mod file. The only time this flag is needed is if no other
+// flags are specified, as in 'go mod -fmt'.
+//
+// The -graph flag prints the module requirement graph (with replacements applied)
+// in text form. Each line in the output has two space-separated fields: a module
+// and one of its requirements. Each module is identified as a string of the form
+// path@version, except for the main module, which has no @version suffix.
+//
+// The -json flag prints the go.mod file in JSON format corresponding to these
+// Go types:
+//
+// 	type Module struct {
+// 		Path string
+// 		Version string
+// 	}
+//
+// 	type GoMod struct {
+// 		Module Module
+// 		Require []Require
+// 		Exclude []Module
+// 		Replace []Replace
+// 	}
+//
+// 	type Require struct {
+// 		Path string
+// 		Version string
+// 		Indirect bool
+// 	}
+//
+// 	type Replace string {
+// 		Old Module
+// 		New Module
+// 	}
+//
+// 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'.
+//
+// The next group of operations provide higher-level editing and maintenance
+// of a module, beyond the go.mod file.
+//
+// The -packages flag prints a list of packages in the module.
+// It only identifies directories containing Go source code;
+// it does not check that those directories contain code that builds.
+//
+// The -fix flag updates go.mod to use canonical version identifiers and
+// to be semantically consistent. For example, consider this go.mod file:
+//
+// 	module M
+//
+// 	require (
+// 		A v1
+// 		B v1.0.0
+// 		C v1.0.0
+// 		D v1.2.3
+// 		E dev
+// 	)
+//
+// 	exclude D v1.2.3
+//
+// First, -fix rewrites non-canonical version identifiers to semver form, so
+// A's v1 becomes v1.0.0 and E's dev becomes the pseudo-version for the latest
+// commit on the dev branch, perhaps v0.0.0-20180523231146-b3f5c0f6e5f1.
+//
+// Next, -fix updates requirements to respect exclusions, so the requirement
+// on the excluded D v1.2.3 is updated to use the next available version of D,
+// 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.
+//
+// Although -fix runs the fix-up operation in isolation, the fix-up also
+// runs automatically any time a go command uses the module graph,
+// to update go.mod to reflect reality. For example, the -sync, -vendor,
+// and -verify flags all effectively imply -fix. And because the module
+// graph defines the meaning of import statements, any commands
+// that load packages—'go build', 'go test', 'go list', and so on—also
+// effectively imply 'go mod -fix'.
+//
+// The -sync flag synchronizes go.mod with the source code in the module.
+// It adds any missing modules necessary to build the current module's
+// packages and dependencies, and it removes unused modules that
+// don't provide any relevant packages. It also adds any missing entries
+// to go.sum and removes any unnecessary ones.
+//
+// The -vendor flag resets the module's vendor directory to include all
+// packages needed to build and test all the module's packages.
+// It does not include any test code for the vendored packages.
+//
+// The -verify flag checks that the dependencies of the current module,
+// which are stored in a local downloaded source cache, have not been
+// modified since being downloaded. If all the modules are unmodified,
+// -verify prints "all modules verified." Otherwise it reports which
+// modules have been changed and causes 'go mod' to exit with a
+// non-zero status.
+//
 //
 // Compile and run Go program
 //
@@ -1069,6 +1325,8 @@
 // 		Examples are linux, darwin, windows, netbsd.
 // 	GOPATH
 // 		For more details see: 'go help gopath'.
+// 	GOPROXY
+// 		URL of Go module proxy. See 'go help goproxy'.
 // 	GORACE
 // 		Options for the race detector.
 // 		See https://golang.org/doc/articles/race_detector.html.
@@ -1262,6 +1520,12 @@
 //
 // See https://golang.org/doc/code.html for an example.
 //
+// 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)
+// and compiled commands (in GOPATH/bin).
+//
 // Internal Directories
 //
 // Code in or below a directory named "internal" is importable only
@@ -1422,6 +1686,7 @@
 // that repository. The supported version control systems are:
 //
 // 	Bazaar      .bzr
+// 	Fossil      .fossil
 // 	Git         .git
 // 	Mercurial   .hg
 // 	Subversion  .svn
@@ -1465,7 +1730,7 @@
 // In particular, it should appear before any raw JavaScript or CSS,
 // to avoid confusing the go command's restricted parser.
 //
-// The vcs is one of "git", "hg", "svn", etc,
+// The vcs is one of "bzr", "fossil", "git", "hg", "svn".
 //
 // The repo-root is the root of the version control system
 // containing a scheme and not containing a .vcs qualifier.
@@ -1487,12 +1752,22 @@
 // same meta tag and then git clone https://code.org/r/p/exproj into
 // GOPATH/src/example.org.
 //
-// New downloaded packages are written to the first directory listed in the GOPATH
+// When using GOPATH, downloaded packages are written to the first directory
-// environment variable (For more details see: 'go help gopath').
+// listed in the GOPATH environment variable.
+// (See 'go help gopath-get' and 'go help gopath'.)
 //
-// The go command attempts to download the version of the
+// When using modules, downloaded packages are stored in the module cache.
-// package appropriate for the Go release being used.
+// (See 'go help modules-get' and 'go help goproxy'.)
-// Run 'go help get' for more.
+//
+// When using modules, an additional variant of the go-import meta tag is
+// recognized and is preferred over those listing version control systems.
+// That variant uses "mod" as the vcs in the content value, as in:
+//
+// 	<meta name="go-import" content="example.org mod https://code.org/moduleproxy">
+//
+// This tag means to fetch modules with paths beginning with example.org
+// from the module proxy available at the URL https://code.org/moduleproxy.
+// See 'go help goproxy' for details about the proxy protocol.
 //
 // Import path checking
 //
@@ -1515,10 +1790,473 @@
 // This makes it possible to copy code into alternate locations in vendor trees
 // without needing to update import comments.
 //
+// Import path checking is also disabled when using modules.
+// Import path comments are obsoleted by the go.mod file's module statement.
+//
 // See https://golang.org/s/go14customimport for details.
 //
 //
-// Package lists
+// Modules, module versions, and more
+//
+// A module is a collection of related Go packages.
+// Modules are the unit of source code interchange and versioning.
+// The go command has direct support for working with modules,
+// including recording and resolving dependencies on other modules.
+// Modules replace the old GOPATH-based approach to specifying
+// which source files are used in a given build.
+//
+// Experimental module support
+//
+// Go 1.11 includes experimental 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),
+// and then at a later point we may remove support for work
+// in GOPATH and the old 'go get' command.
+//
+// The quickest way to take advantage of the new Go 1.11 module support
+// is to check out your repository into a directory outside GOPATH/src,
+// create a go.mod file (described in the next section) there, and run
+// go commands from within that file tree.
+//
+// For more fine-grained control, the module support in Go 1.11 respects
+// a temporary environment variable, GO111MODULE, which can be set to one
+// of three string values: off, on, or auto (the default).
+// If GO111MODULE=off, then the go command never uses the
+// new module support. Instead it looks in vendor directories and GOPATH
+// to find dependencies; we now refer to this as "GOPATH mode."
+// 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=auto or is unset, then the go command enables or
+// disables module support based on the current directory.
+// Module support is enabled only when the current directory is outside
+// GOPATH/src and itself contains a go.mod file or is below a directory
+// 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)
+// and installed commands (in GOPATH/bin, unless GOBIN is set).
+//
+// Defining a module
+//
+// A module is defined by a tree of Go source files with a go.mod file
+// in the tree's root directory. The directory containing the go.mod file
+// is called the module root. Typically the module root will also correspond
+// to a source code repository root (but in general it need not).
+// The module is the set of all Go packages in the module root and its
+// subdirectories, but excluding subtrees with their own go.mod files.
+//
+// The "module path" is the import path prefix corresponding to the module root.
+// The go.mod file defines the module path and lists the specific versions
+// of other modules that should be used when resolving imports during a build,
+// by giving their module paths and versions.
+//
+// For example, this go.mod declares that the directory containing it is the root
+// of the module with path example.com/m, and it also declares that the module
+// depends on specific versions of golang.org/x/text and gopkg.in/yaml.v2:
+//
+// 	module example.com/m
+//
+// 	require (
+// 		golang.org/x/text v0.3.0
+// 		gopkg.in/yaml.v2 v2.1.0
+// 	)
+//
+// The go.mod file can also specify replacements and excluded versions
+// that only apply when building the module directly; they are ignored
+// when the module is incorporated into a larger build.
+// For more about the go.mod file, see https://research.swtch.com/vgo-module.
+//
+// To start a new module, simply create a go.mod file in the root of the
+// module's directory tree, containing only a module statement.
+// The 'go mod' command can be used to do this:
+//
+// 	go mod -init -module example.com/m
+//
+// In a project already using an existing dependency management tool like
+// godep, glide, or dep, 'go mod -init' will also add require statements
+// matching the existing configuration.
+//
+// Once the go.mod file exists, no additional steps are required:
+// go commands like 'go build', 'go test', or even 'go list' will automatically
+// add new dependencies as needed to satisfy imports.
+//
+// The main module and the build list
+//
+// The "main module" is the module containing the directory where the go command
+// is run. The go command finds the module root by looking for a go.mod in the
+// current directory, or else the current directory's parent directory,
+// or else the parent's parent directory, and so on.
+//
+// The main module's go.mod file defines the precise set of packages available
+// for use by the go command, through require, replace, and exclude statements.
+// Dependency modules, found by following require statements, also contribute
+// to the definition of that set of packages, but only through their go.mod
+// files' require statements: any replace and exclude statements in dependency
+// modules are ignored. The replace and exclude statements therefore allow the
+// main module complete control over its own build, without also being subject
+// to complete control by dependencies.
+//
+// The set of modules providing packages to builds is called the "build list".
+// The build list initially contains only the main module. Then the go command
+// adds to the list the exact module versions required by modules already
+// on the list, recursively, until there is nothing left to add to the list.
+// If multiple versions of a particular module are added to the list,
+// then at the end only the latest version (according to semantic version
+// ordering) is kept for use in the build.
+//
+// The 'go list' command provides information about the main module
+// and the build list. For example:
+//
+// 	go list -m              # print path of main module
+// 	go list -m -f={{.Dir}}  # print root directory of main module
+// 	go list -m all          # print build list
+//
+// Maintaining module requirements
+//
+// 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 -sync' 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 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.
+//
+// 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'.
+//
+// Pseudo-versions
+//
+// The go.mod file and the go command more generally use semantic versions as
+// the standard form for describing module versions, so that versions can be
+// compared to determine which should be considered earlier or later than another.
+// A module version like v1.2.3 is introduced by tagging a revision in the
+// underlying source repository. Untagged revisions can be referred to
+// using a "pseudo-version" like v0.0.0-yyyymmddhhmmss-abcdefabcdef,
+// where the time is the commit time in UTC and the final suffix is the prefix
+// of the commit hash. The time portion ensures that two pseudo-versions can
+// be compared to determine which happened later, the commit hash identifes
+// the underlying commit, and the prefix (v0.0.0- in this example) is derived from
+// the most recent tagged version in the commit graph before this commit.
+//
+// There are three pseudo-version forms:
+//
+// vX.0.0-yyyymmddhhmmss-abcdefabcdef is used when there is no earlier
+// versioned commit with an appropriate major version before the target commit.
+// (This was originally the only form, so some older go.mod files use this form
+// even for commits that do follow tags.)
+//
+// vX.Y.Z-pre.0.yyyymmddhhmmss-abcdefabcdef is used when the most
+// recent versioned commit before the target commit is vX.Y.Z-pre.
+//
+// vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdef is used when the most
+// recent versioned commit before the target commit is vX.Y.Z.
+//
+// Pseudo-versions never need to be typed by hand: the go command will accept
+// the plain commit hash and translate it into a pseudo-version (or a tagged
+// version if available) automatically. This conversion is an example of a
+// module query.
+//
+// Module queries
+//
+// The go command accepts a "module query" in place of a module version
+// both on the command line and in the main module's go.mod file.
+// (After evaluating a query found in the main module's go.mod file,
+// the go command updates the file to replace the query with its result.)
+//
+// A fully-specified semantic version, such as "v1.2.3",
+// evaluates to that specific version.
+//
+// A semantic version prefix, such as "v1" or "v1.2",
+// evaluates to the latest available tagged version with that prefix.
+//
+// A semantic version comparison, such as "<v1.2.3" or ">=v1.5.6",
+// evaluates to the available tagged version nearest to the comparison target
+// (the latest version for < and <=, the earliest version for > and >=).
+//
+// The string "latest" matches the latest available tagged version,
+// or else the underlying source repository's latest untagged revision.
+//
+// A revision identifier for the underlying source repository,
+// such as a commit hash prefix, revision tag, or branch name,
+// selects that specific code revision. If the revision is
+// also tagged with a semantic version, the query evaluates to
+// that semantic version. Otherwise the query evaluates to a
+// pseudo-version for the commit.
+//
+// All queries prefer release versions to pre-release versions.
+// For example, "<v1.2.3" will prefer to return "v1.2.2"
+// instead of "v1.2.3-pre1", even though "v1.2.3-pre1" is nearer
+// to the comparison target.
+//
+// Module versions disallowed by exclude statements in the
+// main module's go.mod are considered unavailable and cannot
+// be returned by queries.
+//
+// For example, these commands are all valid:
+//
+// 	go get github.com/gorilla/mux@latest    # same (@latest is default for 'go get')
+// 	go get github.com/gorilla/mux@v1.6.2    # records v1.6.2
+// 	go get github.com/gorilla/mux@e3702bed2 # records v1.6.2
+// 	go get github.com/gorilla/mux@c856192   # records v0.0.0-20180517173623-c85619274f5d
+// 	go get github.com/gorilla/mux@master    # records current meaning of master
+//
+// Module compatibility and semantic versioning
+//
+// The go command requires that modules use semantic versions and expects that
+// the versions accurately describe compatibility: it assumes that v1.5.4 is a
+// backwards-compatible replacement for v1.5.3, v1.4.0, and even v1.0.0.
+// More generally the go command expects that packages follow the
+// "import compatibility rule", which says:
+//
+// "If an old package and a new package have the same import path,
+// the new package must be backwards compatible with the old package."
+//
+// Because the go command assumes the import compatibility rule,
+// a module definition can only set the minimum required version of one
+// of its dependencies: it cannot set a maximum or exclude selected versions.
+// Still, the import compatibility rule is not a guarantee: it may be that
+// v1.5.4 is buggy and not a backwards-compatible replacement for v1.5.3.
+// Because of this, the go command never updates from an older version
+// to a newer version of a module unasked.
+//
+// In semantic versioning, changing the major version number indicates a lack
+// of backwards compatibility with earlier versions. To preserve import
+// compatibility, the go command requires that modules with major version v2
+// or later use a module path with that major version as the final element.
+// For example, version v2.0.0 of example.com/m must instead use module path
+// example.com/m/v2, and packages in that module would use that path as
+// their import path prefix, as in example.com/m/v2/sub/pkg. Including the
+// major version number in the module path and import paths in this way is
+// called "semantic import versioning". Pseudo-versions for modules with major
+// version v2 and later begin with that major version instead of v0, as in
+// v2.0.0-20180326061214-4fc5987536ef.
+//
+// As a special case, module paths beginning with gopkg.in/ continue to use the
+// conventions established on that system: the major version is always present,
+// and it is preceded by a dot instead of a slash: gopkg.in/yaml.v1
+// and gopkg.in/yaml.v2, not gopkg.in/yaml and gopkg.in/yaml/v2.
+//
+// The go command treats modules with different module paths as unrelated:
+// it makes no connection between example.com/m and example.com/m/v2.
+// Modules with different major versions can be used together in a build
+// and are kept separate by the fact that their packages use different
+// import paths.
+//
+// In semantic versioning, major version v0 is for initial development,
+// indicating no expectations of stability or backwards compatibility.
+// Major version v0 does not appear in the module path, because those
+// versions are preparation for v1.0.0, and v1 does not appear in the
+// module path either.
+//
+// Code written before the semantic import versioning convention
+// was introduced may use major versions v2 and later to describe
+// the same set of unversioned import paths as used in v0 and v1.
+// To accommodate such code, if a source code repository has a
+// v2.0.0 or later tag for a file tree with no go.mod, the version is
+// considered to be part of the v1 module's available versions
+// and is given an +incompatible suffix when converted to a module
+// version, as in v2.0.0+incompatible. The +incompatible tag is also
+// applied to pseudo-versions derived from such versions, as in
+// v2.0.1-0.yyyymmddhhmmss-abcdefabcdef+incompatible.
+//
+// In general, having a dependency in the build list (as reported by 'go list -m all')
+// on a v0 version, pre-release version, pseudo-version, or +incompatible version
+// is an indication that problems are more likely when upgrading that
+// dependency, since there is no expectation of compatibility for those.
+//
+// See https://research.swtch.com/vgo-import for more information about
+// semantic import versioning, and see https://semver.org/ for more about
+// semantic versioning.
+//
+// Module code layout
+//
+// For now, see https://research.swtch.com/vgo-module for information
+// about how source code in version control systems is mapped to
+// module file trees.
+//
+// TODO: Add documentation to go command.
+//
+// Module downloading and verification
+//
+// The go command maintains, in the main module's root directory alongside
+// go.mod, a file named go.sum containing the expected cryptographic checksums
+// of the content of specific module versions. Each time a dependency is
+// used, its checksum is added to go.sum if missing or else required to match
+// the existing entry in go.sum.
+//
+// The go command maintains a cache of downloaded packages and computes
+// and records the cryptographic checksum of each package at download time.
+// In normal operation, the go command checks these pre-computed checksums
+// against the main module's go.sum file, instead of recomputing them on
+// each command invocation. The 'go mod -verify' command checks that
+// the cached copies of module downloads still match both their recorded
+// checksums and the entries in go.sum.
+//
+// The go command can fetch modules from a proxy instead of connecting
+// to source control systems directly, according to the setting of the GOPROXY
+// environment variable.
+//
+// See 'go help goproxy' for details about the proxy and also the format of
+// the cached downloaded packages.
+//
+// Modules and vendoring
+//
+// When using modules, the go command completely ignores vendor directories.
+//
+// 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.
+//
+// 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
+// top-level vendor directory is used; vendor directories in other locations
+// are still ignored.
+//
+//
+// Module-aware go get
+//
+// The 'go get' command changes behavior depending on whether the
+// go command is running in module-aware mode or legacy GOPATH mode.
+// This help text, accessible as 'go help module-get' even in legacy GOPATH mode,
+// describes 'go get' as it operates in module-aware mode.
+//
+// Usage: get [-d] [-m] [-u] [-v] [-insecure] [build flags] [packages]
+//
+// Get resolves and adds dependencies to the current development module
+// and then builds and installs them.
+//
+// The first step is to resolve which dependencies to add.
+//
+// For each named package or package pattern, get must decide which version of
+// the corresponding module to use. By default, get chooses the latest tagged
+// release version, such as v0.4.5 or v1.2.3. If there are no tagged release
+// versions, get chooses the latest tagged prerelease version, such as
+// v0.0.1-pre1. If there are no tagged versions at all, get chooses the latest
+// known commit.
+//
+// This default version selection can be overridden by adding an @version
+// suffix to the package argument, as in 'go get golang.org/x/text@v0.3.0'.
+// For modules stored in source control repositories, the version suffix can
+// also be a commit hash, branch identifier, or other syntax known to the
+// source control system, as in 'go get golang.org/x/text@master'.
+// The version suffix @latest explicitly requests the default behavior
+// described above.
+//
+// If a module under consideration is already a dependency of the current
+// development module, then get will update the required version.
+// Specifying a version earlier than the current required version is valid and
+// downgrades the dependency. The version suffix @none indicates that the
+// dependency should be removed entirely.
+//
+// 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
+// dependencies. Instead it prefers to use the specific dependency versions
+// requested by that module. For example, if the latest A requires module
+// B v1.2.3, while B v1.2.4 and v1.3.1 are also available, then 'go get A'
+// will use the latest A but then use B v1.2.3, as requested by A. (If there
+// are competing requirements for a particular module, then 'go get' resolves
+// those requirements by taking the maximum requested version.)
+//
+// The -u flag instructs get to update dependencies to use newer minor or
+// patch releases when available. Continuing the previous example,
+// 'go get -u A' will use the latest A with B v1.3.1 (not B v1.2.3).
+//
+// The -u=patch flag (not -u patch) instructs get to update dependencies
+// to use newer patch releases when available. Continuing the previous example,
+// 'go get -u=patch A' will use the latest A with B v1.2.4 (not B v1.2.3).
+//
+// In general, adding a new dependency may require upgrading
+// existing dependencies to keep a working build, and 'go get' does
+// this automatically. Similarly, downgrading one dependency may
+// require downgrading other dependenceis, and 'go get' does
+// this automatically as well.
+//
+// The -m flag instructs get to stop here, after resolving, upgrading,
+// and downgrading modules and updating go.mod. When using -m,
+// each specified package path must be a module path as well,
+// not the import path of a package below the module root.
+//
+// The -insecure flag permits fetching from repositories and resolving
+// custom domains using insecure schemes such as HTTP. Use with caution.
+//
+// The second step is to download (if needed), build, and install
+// the named packages.
+//
+// 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.
+// For example 'go get golang.org/x/perf' succeeds even though there
+// is no code corresponding to that import path.
+//
+// Note that package patterns are allowed and are expanded after resolving
+// the module versions. For example, 'go get golang.org/x/perf/cmd/...'
+// 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 the main module,
+// and to the Go package in the current directory, if any. In particular,
+// 'go get -u' and 'go get -u=patch' update all the dependencies of the
+// main module. With no package arguments and also without -u,
+// 'go get' is not much more than 'go install', and 'go get -d' not much
+// more than 'go list'.
+//
+// For more about modules, see 'go help modules'.
+//
+// For more about specifying packages, see 'go help packages'.
+//
+// This text describes the behavior of get using modules to manage source
+// code and dependencies. If instead the go command is running in GOPATH
+// mode, the details of get's flags and effects change, as does 'go help get'.
+// See 'go help modules' and 'go help gopath-get'.
+//
+// See also: go build, go install, go clean, go mod.
+//
+//
+// Package lists and patterns
 //
 // Many commands apply to a set of packages:
 //
@@ -1542,9 +2280,11 @@
 //
 // - "main" denotes the top-level package in a stand-alone executable.
 //
-// - "all" expands to all package directories found in all the GOPATH
+// - "all" expands to all packages found in all the GOPATH
 // trees. For example, 'go list all' lists all the packages on the local
-// system.
+// 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.