From: Russ Cox Date: Wed, 18 Jul 2018 17:30:33 +0000 (-0400) Subject: cmd/go: generate alldocs.go X-Git-Tag: go1.11beta2~12 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=95c3348344de688bbb9aba5474a612442e7d36ad;p=gostls13.git cmd/go: generate alldocs.go Change-Id: I5a82aec66332f52e304f647758221b5f30b4e2b6 Reviewed-on: https://go-review.googlesource.com/124701 Reviewed-by: Bryan C. Mills --- diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index fd281460b1..30d1a095fe 100644 --- a/src/cmd/go/alldocs.go +++ b/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 -// '{{.ImportPath}}'. The struct being passed to the template is: +// syntax of package template. The default output is equivalent +// to -f '{{.ImportPath}}'. The struct being passed to the template is: // // type Package struct { -// Dir string // directory containing package sources -// ImportPath string // import path of package in dir -// ImportComment string // path in import comment on package statement -// Name string // package name -// Doc string // package documentation string -// Target string // install path -// Shlib string // the shared library that contains this package (only set when -linkshared) -// Goroot bool // is this package in the Go root? -// Standard bool // is this package part of the standard Go library? -// Stale bool // would 'go install' do anything for this package? -// StaleReason string // explanation for Stale==true -// Root string // Go root or Go path dir containing this package -// ConflictDir string // this directory shadows Dir in $GOPATH -// BinaryOnly bool // binary-only package: cannot be recompiled from sources -// ForTest string // package is only for use in named test -// DepOnly bool // package is only a dependency, not explicitly listed -// Export string // file containing export data (when using -export) +// Dir string // directory containing package sources +// ImportPath string // import path of package in dir +// ImportComment string // path in import comment on package statement +// Name string // package name +// Doc string // package documentation string +// Target string // install path +// Shlib string // the shared library that contains this package (only set when -linkshared) +// Goroot bool // is this package in the Go root? +// Standard bool // is this package part of the standard Go library? +// Stale bool // would 'go install' do anything for this package? +// StaleReason string // explanation for Stale==true +// Root string // Go root or Go path dir containing this package +// ConflictDir string // this directory shadows Dir in $GOPATH +// BinaryOnly bool // binary-only package: cannot be recompiled from sources +// ForTest string // package is only for use in named test +// DepOnly bool // package is only a dependency, not explicitly listed +// 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 -// Deps []string // all (recursively) imported dependencies -// TestImports []string // imports from TestGoFiles -// XTestImports []string // imports from XTestGoFiles +// Imports []string // import paths used by this package +// ImportMap map[string]string // map from source import to ImportPath (identity entries omitted) +// Deps []string // all (recursively) imported dependencies +// 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 { -// GOARCH string // target architecture -// GOOS string // target operating system -// GOROOT string // Go root -// GOPATH string // Go path -// CgoEnabled bool // whether cgo can be used -// UseAllFiles bool // use files regardless of +build lines, file names -// Compiler string // compiler to assume when computing target paths -// BuildTags []string // build constraints to match in +build lines -// ReleaseTags []string // releases the current release is compatible with -// InstallSuffix string // suffix to use in the name of the install dir -// } +// type Context struct { +// GOARCH string // target architecture +// GOOS string // target operating system +// GOROOT string // Go root +// GOPATH string // Go path +// CgoEnabled bool // whether cgo can be used +// UseAllFiles bool // use files regardless of +build lines, file names +// Compiler string // compiler to assume when computing target paths +// BuildTags []string // build constraints to match in +build lines +// ReleaseTags []string // releases the current release is compatible with +// 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 -// environment variable (For more details see: 'go help gopath'). +// When using GOPATH, downloaded packages are written to the first directory +// listed in the GOPATH environment variable. +// (See 'go help gopath-get' and 'go help gopath'.) +// +// When using modules, downloaded packages are stored in the module cache. +// (See 'go help modules-get' and 'go help goproxy'.) +// +// 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: // -// The go command attempts to download the version of the -// package appropriate for the Go release being used. -// Run 'go help get' for more. +// +// +// 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.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, "