Source file src/cmd/go/alldocs.go

     1  // Copyright 2011 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Code generated by 'go test cmd/go -v -run=^TestDocsUpToDate$ -fixdocs'; DO NOT EDIT.
     6  // Edit the documentation in other files and then execute 'go generate cmd/go' to generate this one.
     7  
     8  // Go is a tool for managing Go source code.
     9  //
    10  // Usage:
    11  //
    12  //	go <command> [arguments]
    13  //
    14  // The commands are:
    15  //
    16  //	bug         start a bug report
    17  //	build       compile packages and dependencies
    18  //	clean       remove object files and cached files
    19  //	doc         show documentation for package or symbol
    20  //	env         print Go environment information
    21  //	fix         update packages to use new APIs
    22  //	fmt         gofmt (reformat) package sources
    23  //	generate    generate Go files by processing source
    24  //	get         add dependencies to current module and install them
    25  //	install     compile and install packages and dependencies
    26  //	list        list packages or modules
    27  //	mod         module maintenance
    28  //	work        workspace maintenance
    29  //	run         compile and run Go program
    30  //	test        test packages
    31  //	tool        run specified go tool
    32  //	version     print Go version
    33  //	vet         report likely mistakes in packages
    34  //
    35  // Use "go help <command>" for more information about a command.
    36  //
    37  // Additional help topics:
    38  //
    39  //	buildconstraint build constraints
    40  //	buildmode       build modes
    41  //	c               calling between Go and C
    42  //	cache           build and test caching
    43  //	environment     environment variables
    44  //	filetype        file types
    45  //	go.mod          the go.mod file
    46  //	gopath          GOPATH environment variable
    47  //	goproxy         module proxy protocol
    48  //	importpath      import path syntax
    49  //	modules         modules, module versions, and more
    50  //	module-auth     module authentication using go.sum
    51  //	packages        package lists and patterns
    52  //	private         configuration for downloading non-public code
    53  //	testflag        testing flags
    54  //	testfunc        testing functions
    55  //	vcs             controlling version control with GOVCS
    56  //
    57  // Use "go help <topic>" for more information about that topic.
    58  //
    59  // # Start a bug report
    60  //
    61  // Usage:
    62  //
    63  //	go bug
    64  //
    65  // Bug opens the default browser and starts a new bug report.
    66  // The report includes useful system information.
    67  //
    68  // # Compile packages and dependencies
    69  //
    70  // Usage:
    71  //
    72  //	go build [-o output] [build flags] [packages]
    73  //
    74  // Build compiles the packages named by the import paths,
    75  // along with their dependencies, but it does not install the results.
    76  //
    77  // If the arguments to build are a list of .go files from a single directory,
    78  // build treats them as a list of source files specifying a single package.
    79  //
    80  // When compiling packages, build ignores files that end in '_test.go'.
    81  //
    82  // When compiling a single main package, build writes the resulting
    83  // executable to an output file named after the last non-major-version
    84  // component of the package import path. The '.exe' suffix is added
    85  // when writing a Windows executable.
    86  // So 'go build example/sam' writes 'sam' or 'sam.exe'.
    87  // 'go build example.com/foo/v2' writes 'foo' or 'foo.exe', not 'v2.exe'.
    88  //
    89  // When compiling a package from a list of .go files, the executable
    90  // is named after the first source file.
    91  // 'go build ed.go rx.go' writes 'ed' or 'ed.exe'.
    92  //
    93  // When compiling multiple packages or a single non-main package,
    94  // build compiles the packages but discards the resulting object,
    95  // serving only as a check that the packages can be built.
    96  //
    97  // The -o flag forces build to write the resulting executable or object
    98  // to the named output file or directory, instead of the default behavior described
    99  // in the last two paragraphs. If the named output is an existing directory or
   100  // ends with a slash or backslash, then any resulting executables
   101  // will be written to that directory.
   102  //
   103  // The build flags are shared by the build, clean, get, install, list, run,
   104  // and test commands:
   105  //
   106  //	-C dir
   107  //		Change to dir before running the command.
   108  //		Any files named on the command line are interpreted after
   109  //		changing directories.
   110  //		If used, this flag must be the first one in the command line.
   111  //	-a
   112  //		force rebuilding of packages that are already up-to-date.
   113  //	-n
   114  //		print the commands but do not run them.
   115  //	-p n
   116  //		the number of programs, such as build commands or
   117  //		test binaries, that can be run in parallel.
   118  //		The default is GOMAXPROCS, normally the number of CPUs available.
   119  //	-race
   120  //		enable data race detection.
   121  //		Supported only on linux/amd64, freebsd/amd64, darwin/amd64, darwin/arm64, windows/amd64,
   122  //		linux/ppc64le and linux/arm64 (only for 48-bit VMA).
   123  //	-msan
   124  //		enable interoperation with memory sanitizer.
   125  //		Supported only on linux/amd64, linux/arm64, linux/loong64, freebsd/amd64
   126  //		and only with Clang/LLVM as the host C compiler.
   127  //		PIE build mode will be used on all platforms except linux/amd64.
   128  //	-asan
   129  //		enable interoperation with address sanitizer.
   130  //		Supported only on linux/arm64, linux/amd64, linux/loong64.
   131  //		Supported on linux/amd64 or linux/arm64 and only with GCC 7 and higher
   132  //		or Clang/LLVM 9 and higher.
   133  //		And supported on linux/loong64 only with Clang/LLVM 16 and higher.
   134  //	-cover
   135  //		enable code coverage instrumentation.
   136  //	-covermode set,count,atomic
   137  //		set the mode for coverage analysis.
   138  //		The default is "set" unless -race is enabled,
   139  //		in which case it is "atomic".
   140  //		The values:
   141  //		set: bool: does this statement run?
   142  //		count: int: how many times does this statement run?
   143  //		atomic: int: count, but correct in multithreaded tests;
   144  //			significantly more expensive.
   145  //		Sets -cover.
   146  //	-coverpkg pattern1,pattern2,pattern3
   147  //		For a build that targets package 'main' (e.g. building a Go
   148  //		executable), apply coverage analysis to each package matching
   149  //		the patterns. The default is to apply coverage analysis to
   150  //		packages in the main Go module. See 'go help packages' for a
   151  //		description of package patterns.  Sets -cover.
   152  //	-v
   153  //		print the names of packages as they are compiled.
   154  //	-work
   155  //		print the name of the temporary work directory and
   156  //		do not delete it when exiting.
   157  //	-x
   158  //		print the commands.
   159  //	-asmflags '[pattern=]arg list'
   160  //		arguments to pass on each go tool asm invocation.
   161  //	-buildmode mode
   162  //		build mode to use. See 'go help buildmode' for more.
   163  //	-buildvcs
   164  //		Whether to stamp binaries with version control information
   165  //		("true", "false", or "auto"). By default ("auto"), version control
   166  //		information is stamped into a binary if the main package, the main module
   167  //		containing it, and the current directory are all in the same repository.
   168  //		Use -buildvcs=false to always omit version control information, or
   169  //		-buildvcs=true to error out if version control information is available but
   170  //		cannot be included due to a missing tool or ambiguous directory structure.
   171  //	-compiler name
   172  //		name of compiler to use, as in runtime.Compiler (gccgo or gc).
   173  //	-gccgoflags '[pattern=]arg list'
   174  //		arguments to pass on each gccgo compiler/linker invocation.
   175  //	-gcflags '[pattern=]arg list'
   176  //		arguments to pass on each go tool compile invocation.
   177  //	-installsuffix suffix
   178  //		a suffix to use in the name of the package installation directory,
   179  //		in order to keep output separate from default builds.
   180  //		If using the -race flag, the install suffix is automatically set to race
   181  //		or, if set explicitly, has _race appended to it. Likewise for the -msan
   182  //		and -asan flags. Using a -buildmode option that requires non-default compile
   183  //		flags has a similar effect.
   184  //	-ldflags '[pattern=]arg list'
   185  //		arguments to pass on each go tool link invocation.
   186  //	-linkshared
   187  //		build code that will be linked against shared libraries previously
   188  //		created with -buildmode=shared.
   189  //	-mod mode
   190  //		module download mode to use: readonly, vendor, or mod.
   191  //		By default, if a vendor directory is present and the go version in go.mod
   192  //		is 1.14 or higher, the go command acts as if -mod=vendor were set.
   193  //		Otherwise, the go command acts as if -mod=readonly were set.
   194  //		See https://golang.org/ref/mod#build-commands for details.
   195  //	-modcacherw
   196  //		leave newly-created directories in the module cache read-write
   197  //		instead of making them read-only.
   198  //	-modfile file
   199  //		in module aware mode, read (and possibly write) an alternate go.mod
   200  //		file instead of the one in the module root directory. A file named
   201  //		"go.mod" must still be present in order to determine the module root
   202  //		directory, but it is not accessed. When -modfile is specified, an
   203  //		alternate go.sum file is also used: its path is derived from the
   204  //		-modfile flag by trimming the ".mod" extension and appending ".sum".
   205  //	-overlay file
   206  //		read a JSON config file that provides an overlay for build operations.
   207  //		The file is a JSON struct with a single field, named 'Replace', that
   208  //		maps each disk file path (a string) to its backing file path, so that
   209  //		a build will run as if the disk file path exists with the contents
   210  //		given by the backing file paths, or as if the disk file path does not
   211  //		exist if its backing file path is empty. Support for the -overlay flag
   212  //		has some limitations: importantly, cgo files included from outside the
   213  //		include path must be in the same directory as the Go package they are
   214  //		included from, and overlays will not appear when binaries and tests are
   215  //		run through go run and go test respectively.
   216  //	-pgo file
   217  //		specify the file path of a profile for profile-guided optimization (PGO).
   218  //		When the special name "auto" is specified, for each main package in the
   219  //		build, the go command selects a file named "default.pgo" in the package's
   220  //		directory if that file exists, and applies it to the (transitive)
   221  //		dependencies of the main package (other packages are not affected).
   222  //		Special name "off" turns off PGO. The default is "auto".
   223  //	-pkgdir dir
   224  //		install and load all packages from dir instead of the usual locations.
   225  //		For example, when building with a non-standard configuration,
   226  //		use -pkgdir to keep generated packages in a separate location.
   227  //	-tags tag,list
   228  //		a comma-separated list of additional build tags to consider satisfied
   229  //		during the build. For more information about build tags, see
   230  //		'go help buildconstraint'. (Earlier versions of Go used a
   231  //		space-separated list, and that form is deprecated but still recognized.)
   232  //	-trimpath
   233  //		remove all file system paths from the resulting executable.
   234  //		Instead of absolute file system paths, the recorded file names
   235  //		will begin either a module path@version (when using modules),
   236  //		or a plain import path (when using the standard library, or GOPATH).
   237  //	-toolexec 'cmd args'
   238  //		a program to use to invoke toolchain programs like vet and asm.
   239  //		For example, instead of running asm, the go command will run
   240  //		'cmd args /path/to/asm <arguments for asm>'.
   241  //		The TOOLEXEC_IMPORTPATH environment variable will be set,
   242  //		matching 'go list -f {{.ImportPath}}' for the package being built.
   243  //
   244  // The -asmflags, -gccgoflags, -gcflags, and -ldflags flags accept a
   245  // space-separated list of arguments to pass to an underlying tool
   246  // during the build. To embed spaces in an element in the list, surround
   247  // it with either single or double quotes. The argument list may be
   248  // preceded by a package pattern and an equal sign, which restricts
   249  // the use of that argument list to the building of packages matching
   250  // that pattern (see 'go help packages' for a description of package
   251  // patterns). Without a pattern, the argument list applies only to the
   252  // packages named on the command line. The flags may be repeated
   253  // with different patterns in order to specify different arguments for
   254  // different sets of packages. If a package matches patterns given in
   255  // multiple flags, the latest match on the command line wins.
   256  // For example, 'go build -gcflags=-S fmt' prints the disassembly
   257  // only for package fmt, while 'go build -gcflags=all=-S fmt'
   258  // prints the disassembly for fmt and all its dependencies.
   259  //
   260  // For more about specifying packages, see 'go help packages'.
   261  // For more about where packages and binaries are installed,
   262  // run 'go help gopath'.
   263  // For more about calling between Go and C/C++, run 'go help c'.
   264  //
   265  // Note: Build adheres to certain conventions such as those described
   266  // by 'go help gopath'. Not all projects can follow these conventions,
   267  // however. Installations that have their own conventions or that use
   268  // a separate software build system may choose to use lower-level
   269  // invocations such as 'go tool compile' and 'go tool link' to avoid
   270  // some of the overheads and design decisions of the build tool.
   271  //
   272  // See also: go install, go get, go clean.
   273  //
   274  // # Remove object files and cached files
   275  //
   276  // Usage:
   277  //
   278  //	go clean [clean flags] [build flags] [packages]
   279  //
   280  // Clean removes object files from package source directories.
   281  // The go command builds most objects in a temporary directory,
   282  // so go clean is mainly concerned with object files left by other
   283  // tools or by manual invocations of go build.
   284  //
   285  // If a package argument is given or the -i or -r flag is set,
   286  // clean removes the following files from each of the
   287  // source directories corresponding to the import paths:
   288  //
   289  //	_obj/            old object directory, left from Makefiles
   290  //	_test/           old test directory, left from Makefiles
   291  //	_testmain.go     old gotest file, left from Makefiles
   292  //	test.out         old test log, left from Makefiles
   293  //	build.out        old test log, left from Makefiles
   294  //	*.[568ao]        object files, left from Makefiles
   295  //
   296  //	DIR(.exe)        from go build
   297  //	DIR.test(.exe)   from go test -c
   298  //	MAINFILE(.exe)   from go build MAINFILE.go
   299  //	*.so             from SWIG
   300  //
   301  // In the list, DIR represents the final path element of the
   302  // directory, and MAINFILE is the base name of any Go source
   303  // file in the directory that is not included when building
   304  // the package.
   305  //
   306  // The -i flag causes clean to remove the corresponding installed
   307  // archive or binary (what 'go install' would create).
   308  //
   309  // The -n flag causes clean to print the remove commands it would execute,
   310  // but not run them.
   311  //
   312  // The -r flag causes clean to be applied recursively to all the
   313  // dependencies of the packages named by the import paths.
   314  //
   315  // The -x flag causes clean to print remove commands as it executes them.
   316  //
   317  // The -cache flag causes clean to remove the entire go build cache.
   318  //
   319  // The -testcache flag causes clean to expire all test results in the
   320  // go build cache.
   321  //
   322  // The -modcache flag causes clean to remove the entire module
   323  // download cache, including unpacked source code of versioned
   324  // dependencies.
   325  //
   326  // The -fuzzcache flag causes clean to remove files stored in the Go build
   327  // cache for fuzz testing. The fuzzing engine caches files that expand
   328  // code coverage, so removing them may make fuzzing less effective until
   329  // new inputs are found that provide the same coverage. These files are
   330  // distinct from those stored in testdata directory; clean does not remove
   331  // those files.
   332  //
   333  // For more about build flags, see 'go help build'.
   334  //
   335  // For more about specifying packages, see 'go help packages'.
   336  //
   337  // # Show documentation for package or symbol
   338  //
   339  // Usage:
   340  //
   341  //	go doc [doc flags] [package|[package.]symbol[.methodOrField]]
   342  //
   343  // Doc prints the documentation comments associated with the item identified by its
   344  // arguments (a package, const, func, type, var, method, or struct field)
   345  // followed by a one-line summary of each of the first-level items "under"
   346  // that item (package-level declarations for a package, methods for a type,
   347  // etc.).
   348  //
   349  // Doc accepts zero, one, or two arguments.
   350  //
   351  // Given no arguments, that is, when run as
   352  //
   353  //	go doc
   354  //
   355  // it prints the package documentation for the package in the current directory.
   356  // If the package is a command (package main), the exported symbols of the package
   357  // are elided from the presentation unless the -cmd flag is provided.
   358  //
   359  // When run with one argument, the argument is treated as a Go-syntax-like
   360  // representation of the item to be documented. What the argument selects depends
   361  // on what is installed in GOROOT and GOPATH, as well as the form of the argument,
   362  // which is schematically one of these:
   363  //
   364  //	go doc <pkg>
   365  //	go doc <sym>[.<methodOrField>]
   366  //	go doc [<pkg>.]<sym>[.<methodOrField>]
   367  //	go doc [<pkg>.][<sym>.]<methodOrField>
   368  //
   369  // The first item in this list matched by the argument is the one whose documentation
   370  // is printed. (See the examples below.) However, if the argument starts with a capital
   371  // letter it is assumed to identify a symbol or method in the current directory.
   372  //
   373  // For packages, the order of scanning is determined lexically in breadth-first order.
   374  // That is, the package presented is the one that matches the search and is nearest
   375  // the root and lexically first at its level of the hierarchy. The GOROOT tree is
   376  // always scanned in its entirety before GOPATH.
   377  //
   378  // If there is no package specified or matched, the package in the current
   379  // directory is selected, so "go doc Foo" shows the documentation for symbol Foo in
   380  // the current package.
   381  //
   382  // The package path must be either a qualified path or a proper suffix of a
   383  // path. The go tool's usual package mechanism does not apply: package path
   384  // elements like . and ... are not implemented by go doc.
   385  //
   386  // When run with two arguments, the first is a package path (full path or suffix),
   387  // and the second is a symbol, or symbol with method or struct field:
   388  //
   389  //	go doc <pkg> <sym>[.<methodOrField>]
   390  //
   391  // In all forms, when matching symbols, lower-case letters in the argument match
   392  // either case but upper-case letters match exactly. This means that there may be
   393  // multiple matches of a lower-case argument in a package if different symbols have
   394  // different cases. If this occurs, documentation for all matches is printed.
   395  //
   396  // Examples:
   397  //
   398  //	go doc
   399  //		Show documentation for current package.
   400  //	go doc Foo
   401  //		Show documentation for Foo in the current package.
   402  //		(Foo starts with a capital letter so it cannot match
   403  //		a package path.)
   404  //	go doc encoding/json
   405  //		Show documentation for the encoding/json package.
   406  //	go doc json
   407  //		Shorthand for encoding/json.
   408  //	go doc json.Number (or go doc json.number)
   409  //		Show documentation and method summary for json.Number.
   410  //	go doc json.Number.Int64 (or go doc json.number.int64)
   411  //		Show documentation for json.Number's Int64 method.
   412  //	go doc cmd/doc
   413  //		Show package docs for the doc command.
   414  //	go doc -cmd cmd/doc
   415  //		Show package docs and exported symbols within the doc command.
   416  //	go doc template.new
   417  //		Show documentation for html/template's New function.
   418  //		(html/template is lexically before text/template)
   419  //	go doc text/template.new # One argument
   420  //		Show documentation for text/template's New function.
   421  //	go doc text/template new # Two arguments
   422  //		Show documentation for text/template's New function.
   423  //
   424  //	At least in the current tree, these invocations all print the
   425  //	documentation for json.Decoder's Decode method:
   426  //
   427  //	go doc json.Decoder.Decode
   428  //	go doc json.decoder.decode
   429  //	go doc json.decode
   430  //	cd go/src/encoding/json; go doc decode
   431  //
   432  // Flags:
   433  //
   434  //	-all
   435  //		Show all the documentation for the package.
   436  //	-c
   437  //		Respect case when matching symbols.
   438  //	-cmd
   439  //		Treat a command (package main) like a regular package.
   440  //		Otherwise package main's exported symbols are hidden
   441  //		when showing the package's top-level documentation.
   442  //	-short
   443  //		One-line representation for each symbol.
   444  //	-src
   445  //		Show the full source code for the symbol. This will
   446  //		display the full Go source of its declaration and
   447  //		definition, such as a function definition (including
   448  //		the body), type declaration or enclosing const
   449  //		block. The output may therefore include unexported
   450  //		details.
   451  //	-u
   452  //		Show documentation for unexported as well as exported
   453  //		symbols, methods, and fields.
   454  //
   455  // # Print Go environment information
   456  //
   457  // Usage:
   458  //
   459  //	go env [-json] [-u] [-w] [var ...]
   460  //
   461  // Env prints Go environment information.
   462  //
   463  // By default env prints information as a shell script
   464  // (on Windows, a batch file). If one or more variable
   465  // names is given as arguments, env prints the value of
   466  // each named variable on its own line.
   467  //
   468  // The -json flag prints the environment in JSON format
   469  // instead of as a shell script.
   470  //
   471  // The -u flag requires one or more arguments and unsets
   472  // the default setting for the named environment variables,
   473  // if one has been set with 'go env -w'.
   474  //
   475  // The -w flag requires one or more arguments of the
   476  // form NAME=VALUE and changes the default settings
   477  // of the named environment variables to the given values.
   478  //
   479  // For more about environment variables, see 'go help environment'.
   480  //
   481  // # Update packages to use new APIs
   482  //
   483  // Usage:
   484  //
   485  //	go fix [-fix list] [packages]
   486  //
   487  // Fix runs the Go fix command on the packages named by the import paths.
   488  //
   489  // The -fix flag sets a comma-separated list of fixes to run.
   490  // The default is all known fixes.
   491  // (Its value is passed to 'go tool fix -r'.)
   492  //
   493  // For more about fix, see 'go doc cmd/fix'.
   494  // For more about specifying packages, see 'go help packages'.
   495  //
   496  // To run fix with other options, run 'go tool fix'.
   497  //
   498  // See also: go fmt, go vet.
   499  //
   500  // # Gofmt (reformat) package sources
   501  //
   502  // Usage:
   503  //
   504  //	go fmt [-n] [-x] [packages]
   505  //
   506  // Fmt runs the command 'gofmt -l -w' on the packages named
   507  // by the import paths. It prints the names of the files that are modified.
   508  //
   509  // For more about gofmt, see 'go doc cmd/gofmt'.
   510  // For more about specifying packages, see 'go help packages'.
   511  //
   512  // The -n flag prints commands that would be executed.
   513  // The -x flag prints commands as they are executed.
   514  //
   515  // The -mod flag's value sets which module download mode
   516  // to use: readonly or vendor. See 'go help modules' for more.
   517  //
   518  // To run gofmt with specific options, run gofmt itself.
   519  //
   520  // See also: go fix, go vet.
   521  //
   522  // # Generate Go files by processing source
   523  //
   524  // Usage:
   525  //
   526  //	go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages]
   527  //
   528  // Generate runs commands described by directives within existing
   529  // files. Those commands can run any process but the intent is to
   530  // create or update Go source files.
   531  //
   532  // Go generate is never run automatically by go build, go test,
   533  // and so on. It must be run explicitly.
   534  //
   535  // Go generate scans the file for directives, which are lines of
   536  // the form,
   537  //
   538  //	//go:generate command argument...
   539  //
   540  // (note: no leading spaces and no space in "//go") where command
   541  // is the generator to be run, corresponding to an executable file
   542  // that can be run locally. It must either be in the shell path
   543  // (gofmt), a fully qualified path (/usr/you/bin/mytool), or a
   544  // command alias, described below.
   545  //
   546  // Note that go generate does not parse the file, so lines that look
   547  // like directives in comments or multiline strings will be treated
   548  // as directives.
   549  //
   550  // The arguments to the directive are space-separated tokens or
   551  // double-quoted strings passed to the generator as individual
   552  // arguments when it is run.
   553  //
   554  // Quoted strings use Go syntax and are evaluated before execution; a
   555  // quoted string appears as a single argument to the generator.
   556  //
   557  // To convey to humans and machine tools that code is generated,
   558  // generated source should have a line that matches the following
   559  // regular expression (in Go syntax):
   560  //
   561  //	^// Code generated .* DO NOT EDIT\.$
   562  //
   563  // This line must appear before the first non-comment, non-blank
   564  // text in the file.
   565  //
   566  // Go generate sets several variables when it runs the generator:
   567  //
   568  //	$GOARCH
   569  //		The execution architecture (arm, amd64, etc.)
   570  //	$GOOS
   571  //		The execution operating system (linux, windows, etc.)
   572  //	$GOFILE
   573  //		The base name of the file.
   574  //	$GOLINE
   575  //		The line number of the directive in the source file.
   576  //	$GOPACKAGE
   577  //		The name of the package of the file containing the directive.
   578  //	$GOROOT
   579  //		The GOROOT directory for the 'go' command that invoked the
   580  //		generator, containing the Go toolchain and standard library.
   581  //	$DOLLAR
   582  //		A dollar sign.
   583  //	$PATH
   584  //		The $PATH of the parent process, with $GOROOT/bin
   585  //		placed at the beginning. This causes generators
   586  //		that execute 'go' commands to use the same 'go'
   587  //		as the parent 'go generate' command.
   588  //
   589  // Other than variable substitution and quoted-string evaluation, no
   590  // special processing such as "globbing" is performed on the command
   591  // line.
   592  //
   593  // As a last step before running the command, any invocations of any
   594  // environment variables with alphanumeric names, such as $GOFILE or
   595  // $HOME, are expanded throughout the command line. The syntax for
   596  // variable expansion is $NAME on all operating systems. Due to the
   597  // order of evaluation, variables are expanded even inside quoted
   598  // strings. If the variable NAME is not set, $NAME expands to the
   599  // empty string.
   600  //
   601  // A directive of the form,
   602  //
   603  //	//go:generate -command xxx args...
   604  //
   605  // specifies, for the remainder of this source file only, that the
   606  // string xxx represents the command identified by the arguments. This
   607  // can be used to create aliases or to handle multiword generators.
   608  // For example,
   609  //
   610  //	//go:generate -command foo go tool foo
   611  //
   612  // specifies that the command "foo" represents the generator
   613  // "go tool foo".
   614  //
   615  // Generate processes packages in the order given on the command line,
   616  // one at a time. If the command line lists .go files from a single directory,
   617  // they are treated as a single package. Within a package, generate processes the
   618  // source files in a package in file name order, one at a time. Within
   619  // a source file, generate runs generators in the order they appear
   620  // in the file, one at a time. The go generate tool also sets the build
   621  // tag "generate" so that files may be examined by go generate but ignored
   622  // during build.
   623  //
   624  // For packages with invalid code, generate processes only source files with a
   625  // valid package clause.
   626  //
   627  // If any generator returns an error exit status, "go generate" skips
   628  // all further processing for that package.
   629  //
   630  // The generator is run in the package's source directory.
   631  //
   632  // Go generate accepts two specific flags:
   633  //
   634  //	-run=""
   635  //		if non-empty, specifies a regular expression to select
   636  //		directives whose full original source text (excluding
   637  //		any trailing spaces and final newline) matches the
   638  //		expression.
   639  //
   640  //	-skip=""
   641  //		if non-empty, specifies a regular expression to suppress
   642  //		directives whose full original source text (excluding
   643  //		any trailing spaces and final newline) matches the
   644  //		expression. If a directive matches both the -run and
   645  //		the -skip arguments, it is skipped.
   646  //
   647  // It also accepts the standard build flags including -v, -n, and -x.
   648  // The -v flag prints the names of packages and files as they are
   649  // processed.
   650  // The -n flag prints commands that would be executed.
   651  // The -x flag prints commands as they are executed.
   652  //
   653  // For more about build flags, see 'go help build'.
   654  //
   655  // For more about specifying packages, see 'go help packages'.
   656  //
   657  // # Add dependencies to current module and install them
   658  //
   659  // Usage:
   660  //
   661  //	go get [-t] [-u] [-v] [build flags] [packages]
   662  //
   663  // Get resolves its command-line arguments to packages at specific module versions,
   664  // updates go.mod to require those versions, and downloads source code into the
   665  // module cache.
   666  //
   667  // To add a dependency for a package or upgrade it to its latest version:
   668  //
   669  //	go get example.com/pkg
   670  //
   671  // To upgrade or downgrade a package to a specific version:
   672  //
   673  //	go get example.com/pkg@v1.2.3
   674  //
   675  // To remove a dependency on a module and downgrade modules that require it:
   676  //
   677  //	go get example.com/mod@none
   678  //
   679  // To upgrade the minimum required Go version to the latest released Go version:
   680  //
   681  //	go get go@latest
   682  //
   683  // To upgrade the Go toolchain to the latest patch release of the current Go toolchain:
   684  //
   685  //	go get toolchain@patch
   686  //
   687  // See https://golang.org/ref/mod#go-get for details.
   688  //
   689  // In earlier versions of Go, 'go get' was used to build and install packages.
   690  // Now, 'go get' is dedicated to adjusting dependencies in go.mod. 'go install'
   691  // may be used to build and install commands instead. When a version is specified,
   692  // 'go install' runs in module-aware mode and ignores the go.mod file in the
   693  // current directory. For example:
   694  //
   695  //	go install example.com/pkg@v1.2.3
   696  //	go install example.com/pkg@latest
   697  //
   698  // See 'go help install' or https://golang.org/ref/mod#go-install for details.
   699  //
   700  // 'go get' accepts the following flags.
   701  //
   702  // The -t flag instructs get to consider modules needed to build tests of
   703  // packages specified on the command line.
   704  //
   705  // The -u flag instructs get to update modules providing dependencies
   706  // of packages named on the command line to use newer minor or patch
   707  // releases when available.
   708  //
   709  // The -u=patch flag (not -u patch) also instructs get to update dependencies,
   710  // but changes the default to select patch releases.
   711  //
   712  // When the -t and -u flags are used together, get will update
   713  // test dependencies as well.
   714  //
   715  // The -x flag prints commands as they are executed. This is useful for
   716  // debugging version control commands when a module is downloaded directly
   717  // from a repository.
   718  //
   719  // For more about modules, see https://golang.org/ref/mod.
   720  //
   721  // For more about using 'go get' to update the minimum Go version and
   722  // suggested Go toolchain, see https://go.dev/doc/toolchain.
   723  //
   724  // For more about specifying packages, see 'go help packages'.
   725  //
   726  // This text describes the behavior of get using modules to manage source
   727  // code and dependencies. If instead the go command is running in GOPATH
   728  // mode, the details of get's flags and effects change, as does 'go help get'.
   729  // See 'go help gopath-get'.
   730  //
   731  // See also: go build, go install, go clean, go mod.
   732  //
   733  // # Compile and install packages and dependencies
   734  //
   735  // Usage:
   736  //
   737  //	go install [build flags] [packages]
   738  //
   739  // Install compiles and installs the packages named by the import paths.
   740  //
   741  // Executables are installed in the directory named by the GOBIN environment
   742  // variable, which defaults to $GOPATH/bin or $HOME/go/bin if the GOPATH
   743  // environment variable is not set. Executables in $GOROOT
   744  // are installed in $GOROOT/bin or $GOTOOLDIR instead of $GOBIN.
   745  //
   746  // If the arguments have version suffixes (like @latest or @v1.0.0), "go install"
   747  // builds packages in module-aware mode, ignoring the go.mod file in the current
   748  // directory or any parent directory, if there is one. This is useful for
   749  // installing executables without affecting the dependencies of the main module.
   750  // To eliminate ambiguity about which module versions are used in the build, the
   751  // arguments must satisfy the following constraints:
   752  //
   753  // - Arguments must be package paths or package patterns (with "..." wildcards).
   754  // They must not be standard packages (like fmt), meta-patterns (std, cmd,
   755  // all), or relative or absolute file paths.
   756  //
   757  // - All arguments must have the same version suffix. Different queries are not
   758  // allowed, even if they refer to the same version.
   759  //
   760  // - All arguments must refer to packages in the same module at the same version.
   761  //
   762  // - Package path arguments must refer to main packages. Pattern arguments
   763  // will only match main packages.
   764  //
   765  // - No module is considered the "main" module. If the module containing
   766  // packages named on the command line has a go.mod file, it must not contain
   767  // directives (replace and exclude) that would cause it to be interpreted
   768  // differently than if it were the main module. The module must not require
   769  // a higher version of itself.
   770  //
   771  // - Vendor directories are not used in any module. (Vendor directories are not
   772  // included in the module zip files downloaded by 'go install'.)
   773  //
   774  // If the arguments don't have version suffixes, "go install" may run in
   775  // module-aware mode or GOPATH mode, depending on the GO111MODULE environment
   776  // variable and the presence of a go.mod file. See 'go help modules' for details.
   777  // If module-aware mode is enabled, "go install" runs in the context of the main
   778  // module.
   779  //
   780  // When module-aware mode is disabled, non-main packages are installed in the
   781  // directory $GOPATH/pkg/$GOOS_$GOARCH. When module-aware mode is enabled,
   782  // non-main packages are built and cached but not installed.
   783  //
   784  // Before Go 1.20, the standard library was installed to
   785  // $GOROOT/pkg/$GOOS_$GOARCH.
   786  // Starting in Go 1.20, the standard library is built and cached but not installed.
   787  // Setting GODEBUG=installgoroot=all restores the use of
   788  // $GOROOT/pkg/$GOOS_$GOARCH.
   789  //
   790  // For more about build flags, see 'go help build'.
   791  //
   792  // For more about specifying packages, see 'go help packages'.
   793  //
   794  // See also: go build, go get, go clean.
   795  //
   796  // # List packages or modules
   797  //
   798  // Usage:
   799  //
   800  //	go list [-f format] [-json] [-m] [list flags] [build flags] [packages]
   801  //
   802  // List lists the named packages, one per line.
   803  // The most commonly-used flags are -f and -json, which control the form
   804  // of the output printed for each package. Other list flags, documented below,
   805  // control more specific details.
   806  //
   807  // The default output shows the package import path:
   808  //
   809  //	bytes
   810  //	encoding/json
   811  //	github.com/gorilla/mux
   812  //	golang.org/x/net/html
   813  //
   814  // The -f flag specifies an alternate format for the list, using the
   815  // syntax of package template. The default output is equivalent
   816  // to -f '{{.ImportPath}}'. The struct being passed to the template is:
   817  //
   818  //	type Package struct {
   819  //	    Dir            string   // directory containing package sources
   820  //	    ImportPath     string   // import path of package in dir
   821  //	    ImportComment  string   // path in import comment on package statement
   822  //	    Name           string   // package name
   823  //	    Doc            string   // package documentation string
   824  //	    Target         string   // install path
   825  //	    Shlib          string   // the shared library that contains this package (only set when -linkshared)
   826  //	    Goroot         bool     // is this package in the Go root?
   827  //	    Standard       bool     // is this package part of the standard Go library?
   828  //	    Stale          bool     // would 'go install' do anything for this package?
   829  //	    StaleReason    string   // explanation for Stale==true
   830  //	    Root           string   // Go root or Go path dir containing this package
   831  //	    ConflictDir    string   // this directory shadows Dir in $GOPATH
   832  //	    BinaryOnly     bool     // binary-only package (no longer supported)
   833  //	    ForTest        string   // package is only for use in named test
   834  //	    Export         string   // file containing export data (when using -export)
   835  //	    BuildID        string   // build ID of the compiled package (when using -export)
   836  //	    Module         *Module  // info about package's containing module, if any (can be nil)
   837  //	    Match          []string // command-line patterns matching this package
   838  //	    DepOnly        bool     // package is only a dependency, not explicitly listed
   839  //	    DefaultGODEBUG string  // default GODEBUG setting, for main packages
   840  //
   841  //	    // Source files
   842  //	    GoFiles           []string   // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)
   843  //	    CgoFiles          []string   // .go source files that import "C"
   844  //	    CompiledGoFiles   []string   // .go files presented to compiler (when using -compiled)
   845  //	    IgnoredGoFiles    []string   // .go source files ignored due to build constraints
   846  //	    IgnoredOtherFiles []string // non-.go source files ignored due to build constraints
   847  //	    CFiles            []string   // .c source files
   848  //	    CXXFiles          []string   // .cc, .cxx and .cpp source files
   849  //	    MFiles            []string   // .m source files
   850  //	    HFiles            []string   // .h, .hh, .hpp and .hxx source files
   851  //	    FFiles            []string   // .f, .F, .for and .f90 Fortran source files
   852  //	    SFiles            []string   // .s source files
   853  //	    SwigFiles         []string   // .swig files
   854  //	    SwigCXXFiles      []string   // .swigcxx files
   855  //	    SysoFiles         []string   // .syso object files to add to archive
   856  //	    TestGoFiles       []string   // _test.go files in package
   857  //	    XTestGoFiles      []string   // _test.go files outside package
   858  //
   859  //	    // Embedded files
   860  //	    EmbedPatterns      []string // //go:embed patterns
   861  //	    EmbedFiles         []string // files matched by EmbedPatterns
   862  //	    TestEmbedPatterns  []string // //go:embed patterns in TestGoFiles
   863  //	    TestEmbedFiles     []string // files matched by TestEmbedPatterns
   864  //	    XTestEmbedPatterns []string // //go:embed patterns in XTestGoFiles
   865  //	    XTestEmbedFiles    []string // files matched by XTestEmbedPatterns
   866  //
   867  //	    // Cgo directives
   868  //	    CgoCFLAGS    []string // cgo: flags for C compiler
   869  //	    CgoCPPFLAGS  []string // cgo: flags for C preprocessor
   870  //	    CgoCXXFLAGS  []string // cgo: flags for C++ compiler
   871  //	    CgoFFLAGS    []string // cgo: flags for Fortran compiler
   872  //	    CgoLDFLAGS   []string // cgo: flags for linker
   873  //	    CgoPkgConfig []string // cgo: pkg-config names
   874  //
   875  //	    // Dependency information
   876  //	    Imports      []string          // import paths used by this package
   877  //	    ImportMap    map[string]string // map from source import to ImportPath (identity entries omitted)
   878  //	    Deps         []string          // all (recursively) imported dependencies
   879  //	    TestImports  []string          // imports from TestGoFiles
   880  //	    XTestImports []string          // imports from XTestGoFiles
   881  //
   882  //	    // Error information
   883  //	    Incomplete bool            // this package or a dependency has an error
   884  //	    Error      *PackageError   // error loading package
   885  //	    DepsErrors []*PackageError // errors loading dependencies
   886  //	}
   887  //
   888  // Packages stored in vendor directories report an ImportPath that includes the
   889  // path to the vendor directory (for example, "d/vendor/p" instead of "p"),
   890  // so that the ImportPath uniquely identifies a given copy of a package.
   891  // The Imports, Deps, TestImports, and XTestImports lists also contain these
   892  // expanded import paths. See golang.org/s/go15vendor for more about vendoring.
   893  //
   894  // The error information, if any, is
   895  //
   896  //	type PackageError struct {
   897  //	    ImportStack   []string // shortest path from package named on command line to this one
   898  //	    Pos           string   // position of error (if present, file:line:col)
   899  //	    Err           string   // the error itself
   900  //	}
   901  //
   902  // The module information is a Module struct, defined in the discussion
   903  // of list -m below.
   904  //
   905  // The template function "join" calls strings.Join.
   906  //
   907  // The template function "context" returns the build context, defined as:
   908  //
   909  //	type Context struct {
   910  //	    GOARCH        string   // target architecture
   911  //	    GOOS          string   // target operating system
   912  //	    GOROOT        string   // Go root
   913  //	    GOPATH        string   // Go path
   914  //	    CgoEnabled    bool     // whether cgo can be used
   915  //	    UseAllFiles   bool     // use files regardless of //go:build lines, file names
   916  //	    Compiler      string   // compiler to assume when computing target paths
   917  //	    BuildTags     []string // build constraints to match in //go:build lines
   918  //	    ToolTags      []string // toolchain-specific build constraints
   919  //	    ReleaseTags   []string // releases the current release is compatible with
   920  //	    InstallSuffix string   // suffix to use in the name of the install dir
   921  //	}
   922  //
   923  // For more information about the meaning of these fields see the documentation
   924  // for the go/build package's Context type.
   925  //
   926  // The -json flag causes the package data to be printed in JSON format
   927  // instead of using the template format. The JSON flag can optionally be
   928  // provided with a set of comma-separated required field names to be output.
   929  // If so, those required fields will always appear in JSON output, but
   930  // others may be omitted to save work in computing the JSON struct.
   931  //
   932  // The -compiled flag causes list to set CompiledGoFiles to the Go source
   933  // files presented to the compiler. Typically this means that it repeats
   934  // the files listed in GoFiles and then also adds the Go code generated
   935  // by processing CgoFiles and SwigFiles. The Imports list contains the
   936  // union of all imports from both GoFiles and CompiledGoFiles.
   937  //
   938  // The -deps flag causes list to iterate over not just the named packages
   939  // but also all their dependencies. It visits them in a depth-first post-order
   940  // traversal, so that a package is listed only after all its dependencies.
   941  // Packages not explicitly listed on the command line will have the DepOnly
   942  // field set to true.
   943  //
   944  // The -e flag changes the handling of erroneous packages, those that
   945  // cannot be found or are malformed. By default, the list command
   946  // prints an error to standard error for each erroneous package and
   947  // omits the packages from consideration during the usual printing.
   948  // With the -e flag, the list command never prints errors to standard
   949  // error and instead processes the erroneous packages with the usual
   950  // printing. Erroneous packages will have a non-empty ImportPath and
   951  // a non-nil Error field; other information may or may not be missing
   952  // (zeroed).
   953  //
   954  // The -export flag causes list to set the Export field to the name of a
   955  // file containing up-to-date export information for the given package,
   956  // and the BuildID field to the build ID of the compiled package.
   957  //
   958  // The -find flag causes list to identify the named packages but not
   959  // resolve their dependencies: the Imports and Deps lists will be empty.
   960  // With the -find flag, the -deps, -test and -export commands cannot be
   961  // used.
   962  //
   963  // The -test flag causes list to report not only the named packages
   964  // but also their test binaries (for packages with tests), to convey to
   965  // source code analysis tools exactly how test binaries are constructed.
   966  // The reported import path for a test binary is the import path of
   967  // the package followed by a ".test" suffix, as in "math/rand.test".
   968  // When building a test, it is sometimes necessary to rebuild certain
   969  // dependencies specially for that test (most commonly the tested
   970  // package itself). The reported import path of a package recompiled
   971  // for a particular test binary is followed by a space and the name of
   972  // the test binary in brackets, as in "math/rand [math/rand.test]"
   973  // or "regexp [sort.test]". The ForTest field is also set to the name
   974  // of the package being tested ("math/rand" or "sort" in the previous
   975  // examples).
   976  //
   977  // The Dir, Target, Shlib, Root, ConflictDir, and Export file paths
   978  // are all absolute paths.
   979  //
   980  // By default, the lists GoFiles, CgoFiles, and so on hold names of files in Dir
   981  // (that is, paths relative to Dir, not absolute paths).
   982  // The generated files added when using the -compiled and -test flags
   983  // are absolute paths referring to cached copies of generated Go source files.
   984  // Although they are Go source files, the paths may not end in ".go".
   985  //
   986  // The -m flag causes list to list modules instead of packages.
   987  //
   988  // When listing modules, the -f flag still specifies a format template
   989  // applied to a Go struct, but now a Module struct:
   990  //
   991  //	type Module struct {
   992  //	    Path       string        // module path
   993  //	    Query      string        // version query corresponding to this version
   994  //	    Version    string        // module version
   995  //	    Versions   []string      // available module versions
   996  //	    Replace    *Module       // replaced by this module
   997  //	    Time       *time.Time    // time version was created
   998  //	    Update     *Module       // available update (with -u)
   999  //	    Main       bool          // is this the main module?
  1000  //	    Indirect   bool          // module is only indirectly needed by main module
  1001  //	    Dir        string        // directory holding local copy of files, if any
  1002  //	    GoMod      string        // path to go.mod file describing module, if any
  1003  //	    GoVersion  string        // go version used in module
  1004  //	    Retracted  []string      // retraction information, if any (with -retracted or -u)
  1005  //	    Deprecated string        // deprecation message, if any (with -u)
  1006  //	    Error      *ModuleError  // error loading module
  1007  //	    Sum        string        // checksum for path, version (as in go.sum)
  1008  //	    GoModSum   string        // checksum for go.mod (as in go.sum)
  1009  //	    Origin     any           // provenance of module
  1010  //	    Reuse      bool          // reuse of old module info is safe
  1011  //	}
  1012  //
  1013  //	type ModuleError struct {
  1014  //	    Err string // the error itself
  1015  //	}
  1016  //
  1017  // The file GoMod refers to may be outside the module directory if the
  1018  // module is in the module cache or if the -modfile flag is used.
  1019  //
  1020  // The default output is to print the module path and then
  1021  // information about the version and replacement if any.
  1022  // For example, 'go list -m all' might print:
  1023  //
  1024  //	my/main/module
  1025  //	golang.org/x/text v0.3.0 => /tmp/text
  1026  //	rsc.io/pdf v0.1.1
  1027  //
  1028  // The Module struct has a String method that formats this
  1029  // line of output, so that the default format is equivalent
  1030  // to -f '{{.String}}'.
  1031  //
  1032  // Note that when a module has been replaced, its Replace field
  1033  // describes the replacement module, and its Dir field is set to
  1034  // the replacement's source code, if present. (That is, if Replace
  1035  // is non-nil, then Dir is set to Replace.Dir, with no access to
  1036  // the replaced source code.)
  1037  //
  1038  // The -u flag adds information about available upgrades.
  1039  // When the latest version of a given module is newer than
  1040  // the current one, list -u sets the Module's Update field
  1041  // to information about the newer module. list -u will also set
  1042  // the module's Retracted field if the current version is retracted.
  1043  // The Module's String method indicates an available upgrade by
  1044  // formatting the newer version in brackets after the current version.
  1045  // If a version is retracted, the string "(retracted)" will follow it.
  1046  // For example, 'go list -m -u all' might print:
  1047  //
  1048  //	my/main/module
  1049  //	golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text
  1050  //	rsc.io/pdf v0.1.1 (retracted) [v0.1.2]
  1051  //
  1052  // (For tools, 'go list -m -u -json all' may be more convenient to parse.)
  1053  //
  1054  // The -versions flag causes list to set the Module's Versions field
  1055  // to a list of all known versions of that module, ordered according
  1056  // to semantic versioning, earliest to latest. The flag also changes
  1057  // the default output format to display the module path followed by the
  1058  // space-separated version list.
  1059  //
  1060  // The -retracted flag causes list to report information about retracted
  1061  // module versions. When -retracted is used with -f or -json, the Retracted
  1062  // field will be set to a string explaining why the version was retracted.
  1063  // The string is taken from comments on the retract directive in the
  1064  // module's go.mod file. When -retracted is used with -versions, retracted
  1065  // versions are listed together with unretracted versions. The -retracted
  1066  // flag may be used with or without -m.
  1067  //
  1068  // The arguments to list -m are interpreted as a list of modules, not packages.
  1069  // The main module is the module containing the current directory.
  1070  // The active modules are the main module and its dependencies.
  1071  // With no arguments, list -m shows the main module.
  1072  // With arguments, list -m shows the modules specified by the arguments.
  1073  // Any of the active modules can be specified by its module path.
  1074  // The special pattern "all" specifies all the active modules, first the main
  1075  // module and then dependencies sorted by module path.
  1076  // A pattern containing "..." specifies the active modules whose
  1077  // module paths match the pattern.
  1078  // A query of the form path@version specifies the result of that query,
  1079  // which is not limited to active modules.
  1080  // See 'go help modules' for more about module queries.
  1081  //
  1082  // The template function "module" takes a single string argument
  1083  // that must be a module path or query and returns the specified
  1084  // module as a Module struct. If an error occurs, the result will
  1085  // be a Module struct with a non-nil Error field.
  1086  //
  1087  // When using -m, the -reuse=old.json flag accepts the name of file containing
  1088  // the JSON output of a previous 'go list -m -json' invocation with the
  1089  // same set of modifier flags (such as -u, -retracted, and -versions).
  1090  // The go command may use this file to determine that a module is unchanged
  1091  // since the previous invocation and avoid redownloading information about it.
  1092  // Modules that are not redownloaded will be marked in the new output by
  1093  // setting the Reuse field to true. Normally the module cache provides this
  1094  // kind of reuse automatically; the -reuse flag can be useful on systems that
  1095  // do not preserve the module cache.
  1096  //
  1097  // For more about build flags, see 'go help build'.
  1098  //
  1099  // For more about specifying packages, see 'go help packages'.
  1100  //
  1101  // For more about modules, see https://golang.org/ref/mod.
  1102  //
  1103  // # Module maintenance
  1104  //
  1105  // Go mod provides access to operations on modules.
  1106  //
  1107  // Note that support for modules is built into all the go commands,
  1108  // not just 'go mod'. For example, day-to-day adding, removing, upgrading,
  1109  // and downgrading of dependencies should be done using 'go get'.
  1110  // See 'go help modules' for an overview of module functionality.
  1111  //
  1112  // Usage:
  1113  //
  1114  //	go mod <command> [arguments]
  1115  //
  1116  // The commands are:
  1117  //
  1118  //	download    download modules to local cache
  1119  //	edit        edit go.mod from tools or scripts
  1120  //	graph       print module requirement graph
  1121  //	init        initialize new module in current directory
  1122  //	tidy        add missing and remove unused modules
  1123  //	vendor      make vendored copy of dependencies
  1124  //	verify      verify dependencies have expected content
  1125  //	why         explain why packages or modules are needed
  1126  //
  1127  // Use "go help mod <command>" for more information about a command.
  1128  //
  1129  // # Download modules to local cache
  1130  //
  1131  // Usage:
  1132  //
  1133  //	go mod download [-x] [-json] [-reuse=old.json] [modules]
  1134  //
  1135  // Download downloads the named modules, which can be module patterns selecting
  1136  // dependencies of the main module or module queries of the form path@version.
  1137  //
  1138  // With no arguments, download applies to the modules needed to build and test
  1139  // the packages in the main module: the modules explicitly required by the main
  1140  // module if it is at 'go 1.17' or higher, or all transitively-required modules
  1141  // if at 'go 1.16' or lower.
  1142  //
  1143  // The go command will automatically download modules as needed during ordinary
  1144  // execution. The "go mod download" command is useful mainly for pre-filling
  1145  // the local cache or to compute the answers for a Go module proxy.
  1146  //
  1147  // By default, download writes nothing to standard output. It may print progress
  1148  // messages and errors to standard error.
  1149  //
  1150  // The -json flag causes download to print a sequence of JSON objects
  1151  // to standard output, describing each downloaded module (or failure),
  1152  // corresponding to this Go struct:
  1153  //
  1154  //	type Module struct {
  1155  //	    Path     string // module path
  1156  //	    Query    string // version query corresponding to this version
  1157  //	    Version  string // module version
  1158  //	    Error    string // error loading module
  1159  //	    Info     string // absolute path to cached .info file
  1160  //	    GoMod    string // absolute path to cached .mod file
  1161  //	    Zip      string // absolute path to cached .zip file
  1162  //	    Dir      string // absolute path to cached source root directory
  1163  //	    Sum      string // checksum for path, version (as in go.sum)
  1164  //	    GoModSum string // checksum for go.mod (as in go.sum)
  1165  //	    Origin   any    // provenance of module
  1166  //	    Reuse    bool   // reuse of old module info is safe
  1167  //	}
  1168  //
  1169  // The -reuse flag accepts the name of file containing the JSON output of a
  1170  // previous 'go mod download -json' invocation. The go command may use this
  1171  // file to determine that a module is unchanged since the previous invocation
  1172  // and avoid redownloading it. Modules that are not redownloaded will be marked
  1173  // in the new output by setting the Reuse field to true. Normally the module
  1174  // cache provides this kind of reuse automatically; the -reuse flag can be
  1175  // useful on systems that do not preserve the module cache.
  1176  //
  1177  // The -x flag causes download to print the commands download executes.
  1178  //
  1179  // See https://golang.org/ref/mod#go-mod-download for more about 'go mod download'.
  1180  //
  1181  // See https://golang.org/ref/mod#version-queries for more about version queries.
  1182  //
  1183  // # Edit go.mod from tools or scripts
  1184  //
  1185  // Usage:
  1186  //
  1187  //	go mod edit [editing flags] [-fmt|-print|-json] [go.mod]
  1188  //
  1189  // Edit provides a command-line interface for editing go.mod,
  1190  // for use primarily by tools or scripts. It reads only go.mod;
  1191  // it does not look up information about the modules involved.
  1192  // By default, edit reads and writes the go.mod file of the main module,
  1193  // but a different target file can be specified after the editing flags.
  1194  //
  1195  // The editing flags specify a sequence of editing operations.
  1196  //
  1197  // The -fmt flag reformats the go.mod file without making other changes.
  1198  // This reformatting is also implied by any other modifications that use or
  1199  // rewrite the go.mod file. The only time this flag is needed is if no other
  1200  // flags are specified, as in 'go mod edit -fmt'.
  1201  //
  1202  // The -module flag changes the module's path (the go.mod file's module line).
  1203  //
  1204  // The -require=path@version and -droprequire=path flags
  1205  // add and drop a requirement on the given module path and version.
  1206  // Note that -require overrides any existing requirements on path.
  1207  // These flags are mainly for tools that understand the module graph.
  1208  // Users should prefer 'go get path@version' or 'go get path@none',
  1209  // which make other go.mod adjustments as needed to satisfy
  1210  // constraints imposed by other modules.
  1211  //
  1212  // The -exclude=path@version and -dropexclude=path@version flags
  1213  // add and drop an exclusion for the given module path and version.
  1214  // Note that -exclude=path@version is a no-op if that exclusion already exists.
  1215  //
  1216  // The -replace=old[@v]=new[@v] flag adds a replacement of the given
  1217  // module path and version pair. If the @v in old@v is omitted, a
  1218  // replacement without a version on the left side is added, which applies
  1219  // to all versions of the old module path. If the @v in new@v is omitted,
  1220  // the new path should be a local module root directory, not a module
  1221  // path. Note that -replace overrides any redundant replacements for old[@v],
  1222  // so omitting @v will drop existing replacements for specific versions.
  1223  //
  1224  // The -dropreplace=old[@v] flag drops a replacement of the given
  1225  // module path and version pair. If the @v is omitted, a replacement without
  1226  // a version on the left side is dropped.
  1227  //
  1228  // The -retract=version and -dropretract=version flags add and drop a
  1229  // retraction on the given version. The version may be a single version
  1230  // like "v1.2.3" or a closed interval like "[v1.1.0,v1.1.9]". Note that
  1231  // -retract=version is a no-op if that retraction already exists.
  1232  //
  1233  // The -require, -droprequire, -exclude, -dropexclude, -replace,
  1234  // -dropreplace, -retract, and -dropretract editing flags may be repeated,
  1235  // and the changes are applied in the order given.
  1236  //
  1237  // The -go=version flag sets the expected Go language version.
  1238  //
  1239  // The -toolchain=name flag sets the Go toolchain to use.
  1240  //
  1241  // The -print flag prints the final go.mod in its text format instead of
  1242  // writing it back to go.mod.
  1243  //
  1244  // The -json flag prints the final go.mod file in JSON format instead of
  1245  // writing it back to go.mod. The JSON output corresponds to these Go types:
  1246  //
  1247  //	type Module struct {
  1248  //		Path    string
  1249  //		Version string
  1250  //	}
  1251  //
  1252  //	type GoMod struct {
  1253  //		Module    ModPath
  1254  //		Go        string
  1255  //		Toolchain string
  1256  //		Require   []Require
  1257  //		Exclude   []Module
  1258  //		Replace   []Replace
  1259  //		Retract   []Retract
  1260  //	}
  1261  //
  1262  //	type ModPath struct {
  1263  //		Path       string
  1264  //		Deprecated string
  1265  //	}
  1266  //
  1267  //	type Require struct {
  1268  //		Path string
  1269  //		Version string
  1270  //		Indirect bool
  1271  //	}
  1272  //
  1273  //	type Replace struct {
  1274  //		Old Module
  1275  //		New Module
  1276  //	}
  1277  //
  1278  //	type Retract struct {
  1279  //		Low       string
  1280  //		High      string
  1281  //		Rationale string
  1282  //	}
  1283  //
  1284  // Retract entries representing a single version (not an interval) will have
  1285  // the "Low" and "High" fields set to the same value.
  1286  //
  1287  // Note that this only describes the go.mod file itself, not other modules
  1288  // referred to indirectly. For the full set of modules available to a build,
  1289  // use 'go list -m -json all'.
  1290  //
  1291  // Edit also provides the -C, -n, and -x build flags.
  1292  //
  1293  // See https://golang.org/ref/mod#go-mod-edit for more about 'go mod edit'.
  1294  //
  1295  // # Print module requirement graph
  1296  //
  1297  // Usage:
  1298  //
  1299  //	go mod graph [-go=version] [-x]
  1300  //
  1301  // Graph prints the module requirement graph (with replacements applied)
  1302  // in text form. Each line in the output has two space-separated fields: a module
  1303  // and one of its requirements. Each module is identified as a string of the form
  1304  // path@version, except for the main module, which has no @version suffix.
  1305  //
  1306  // The -go flag causes graph to report the module graph as loaded by the
  1307  // given Go version, instead of the version indicated by the 'go' directive
  1308  // in the go.mod file.
  1309  //
  1310  // The -x flag causes graph to print the commands graph executes.
  1311  //
  1312  // See https://golang.org/ref/mod#go-mod-graph for more about 'go mod graph'.
  1313  //
  1314  // # Initialize new module in current directory
  1315  //
  1316  // Usage:
  1317  //
  1318  //	go mod init [module-path]
  1319  //
  1320  // Init initializes and writes a new go.mod file in the current directory, in
  1321  // effect creating a new module rooted at the current directory. The go.mod file
  1322  // must not already exist.
  1323  //
  1324  // Init accepts one optional argument, the module path for the new module. If the
  1325  // module path argument is omitted, init will attempt to infer the module path
  1326  // using import comments in .go files, vendoring tool configuration files (like
  1327  // Gopkg.lock), and the current directory (if in GOPATH).
  1328  //
  1329  // See https://golang.org/ref/mod#go-mod-init for more about 'go mod init'.
  1330  //
  1331  // # Add missing and remove unused modules
  1332  //
  1333  // Usage:
  1334  //
  1335  //	go mod tidy [-e] [-v] [-x] [-go=version] [-compat=version]
  1336  //
  1337  // Tidy makes sure go.mod matches the source code in the module.
  1338  // It adds any missing modules necessary to build the current module's
  1339  // packages and dependencies, and it removes unused modules that
  1340  // don't provide any relevant packages. It also adds any missing entries
  1341  // to go.sum and removes any unnecessary ones.
  1342  //
  1343  // The -v flag causes tidy to print information about removed modules
  1344  // to standard error.
  1345  //
  1346  // The -e flag causes tidy to attempt to proceed despite errors
  1347  // encountered while loading packages.
  1348  //
  1349  // The -go flag causes tidy to update the 'go' directive in the go.mod
  1350  // file to the given version, which may change which module dependencies
  1351  // are retained as explicit requirements in the go.mod file.
  1352  // (Go versions 1.17 and higher retain more requirements in order to
  1353  // support lazy module loading.)
  1354  //
  1355  // The -compat flag preserves any additional checksums needed for the
  1356  // 'go' command from the indicated major Go release to successfully load
  1357  // the module graph, and causes tidy to error out if that version of the
  1358  // 'go' command would load any imported package from a different module
  1359  // version. By default, tidy acts as if the -compat flag were set to the
  1360  // version prior to the one indicated by the 'go' directive in the go.mod
  1361  // file.
  1362  //
  1363  // The -x flag causes tidy to print the commands download executes.
  1364  //
  1365  // See https://golang.org/ref/mod#go-mod-tidy for more about 'go mod tidy'.
  1366  //
  1367  // # Make vendored copy of dependencies
  1368  //
  1369  // Usage:
  1370  //
  1371  //	go mod vendor [-e] [-v] [-o outdir]
  1372  //
  1373  // Vendor resets the main module's vendor directory to include all packages
  1374  // needed to build and test all the main module's packages.
  1375  // It does not include test code for vendored packages.
  1376  //
  1377  // The -v flag causes vendor to print the names of vendored
  1378  // modules and packages to standard error.
  1379  //
  1380  // The -e flag causes vendor to attempt to proceed despite errors
  1381  // encountered while loading packages.
  1382  //
  1383  // The -o flag causes vendor to create the vendor directory at the given
  1384  // path instead of "vendor". The go command can only use a vendor directory
  1385  // named "vendor" within the module root directory, so this flag is
  1386  // primarily useful for other tools.
  1387  //
  1388  // See https://golang.org/ref/mod#go-mod-vendor for more about 'go mod vendor'.
  1389  //
  1390  // # Verify dependencies have expected content
  1391  //
  1392  // Usage:
  1393  //
  1394  //	go mod verify
  1395  //
  1396  // Verify checks that the dependencies of the current module,
  1397  // which are stored in a local downloaded source cache, have not been
  1398  // modified since being downloaded. If all the modules are unmodified,
  1399  // verify prints "all modules verified." Otherwise it reports which
  1400  // modules have been changed and causes 'go mod' to exit with a
  1401  // non-zero status.
  1402  //
  1403  // See https://golang.org/ref/mod#go-mod-verify for more about 'go mod verify'.
  1404  //
  1405  // # Explain why packages or modules are needed
  1406  //
  1407  // Usage:
  1408  //
  1409  //	go mod why [-m] [-vendor] packages...
  1410  //
  1411  // Why shows a shortest path in the import graph from the main module to
  1412  // each of the listed packages. If the -m flag is given, why treats the
  1413  // arguments as a list of modules and finds a path to any package in each
  1414  // of the modules.
  1415  //
  1416  // By default, why queries the graph of packages matched by "go list all",
  1417  // which includes tests for reachable packages. The -vendor flag causes why
  1418  // to exclude tests of dependencies.
  1419  //
  1420  // The output is a sequence of stanzas, one for each package or module
  1421  // name on the command line, separated by blank lines. Each stanza begins
  1422  // with a comment line "# package" or "# module" giving the target
  1423  // package or module. Subsequent lines give a path through the import
  1424  // graph, one package per line. If the package or module is not
  1425  // referenced from the main module, the stanza will display a single
  1426  // parenthesized note indicating that fact.
  1427  //
  1428  // For example:
  1429  //
  1430  //	$ go mod why golang.org/x/text/language golang.org/x/text/encoding
  1431  //	# golang.org/x/text/language
  1432  //	rsc.io/quote
  1433  //	rsc.io/sampler
  1434  //	golang.org/x/text/language
  1435  //
  1436  //	# golang.org/x/text/encoding
  1437  //	(main module does not need package golang.org/x/text/encoding)
  1438  //	$
  1439  //
  1440  // See https://golang.org/ref/mod#go-mod-why for more about 'go mod why'.
  1441  //
  1442  // # Workspace maintenance
  1443  //
  1444  // Work provides access to operations on workspaces.
  1445  //
  1446  // Note that support for workspaces is built into many other commands, not
  1447  // just 'go work'.
  1448  //
  1449  // See 'go help modules' for information about Go's module system of which
  1450  // workspaces are a part.
  1451  //
  1452  // See https://go.dev/ref/mod#workspaces for an in-depth reference on
  1453  // workspaces.
  1454  //
  1455  // See https://go.dev/doc/tutorial/workspaces for an introductory
  1456  // tutorial on workspaces.
  1457  //
  1458  // A workspace is specified by a go.work file that specifies a set of
  1459  // module directories with the "use" directive. These modules are used as
  1460  // root modules by the go command for builds and related operations.  A
  1461  // workspace that does not specify modules to be used cannot be used to do
  1462  // builds from local modules.
  1463  //
  1464  // go.work files are line-oriented. Each line holds a single directive,
  1465  // made up of a keyword followed by arguments. For example:
  1466  //
  1467  //	go 1.18
  1468  //
  1469  //	use ../foo/bar
  1470  //	use ./baz
  1471  //
  1472  //	replace example.com/foo v1.2.3 => example.com/bar v1.4.5
  1473  //
  1474  // The leading keyword can be factored out of adjacent lines to create a block,
  1475  // like in Go imports.
  1476  //
  1477  //	use (
  1478  //	  ../foo/bar
  1479  //	  ./baz
  1480  //	)
  1481  //
  1482  // The use directive specifies a module to be included in the workspace's
  1483  // set of main modules. The argument to the use directive is the directory
  1484  // containing the module's go.mod file.
  1485  //
  1486  // The go directive specifies the version of Go the file was written at. It
  1487  // is possible there may be future changes in the semantics of workspaces
  1488  // that could be controlled by this version, but for now the version
  1489  // specified has no effect.
  1490  //
  1491  // The replace directive has the same syntax as the replace directive in a
  1492  // go.mod file and takes precedence over replaces in go.mod files.  It is
  1493  // primarily intended to override conflicting replaces in different workspace
  1494  // modules.
  1495  //
  1496  // To determine whether the go command is operating in workspace mode, use
  1497  // the "go env GOWORK" command. This will specify the workspace file being
  1498  // used.
  1499  //
  1500  // Usage:
  1501  //
  1502  //	go work <command> [arguments]
  1503  //
  1504  // The commands are:
  1505  //
  1506  //	edit        edit go.work from tools or scripts
  1507  //	init        initialize workspace file
  1508  //	sync        sync workspace build list to modules
  1509  //	use         add modules to workspace file
  1510  //	vendor      make vendored copy of dependencies
  1511  //
  1512  // Use "go help work <command>" for more information about a command.
  1513  //
  1514  // # Edit go.work from tools or scripts
  1515  //
  1516  // Usage:
  1517  //
  1518  //	go work edit [editing flags] [go.work]
  1519  //
  1520  // Edit provides a command-line interface for editing go.work,
  1521  // for use primarily by tools or scripts. It only reads go.work;
  1522  // it does not look up information about the modules involved.
  1523  // If no file is specified, Edit looks for a go.work file in the current
  1524  // directory and its parent directories
  1525  //
  1526  // The editing flags specify a sequence of editing operations.
  1527  //
  1528  // The -fmt flag reformats the go.work file without making other changes.
  1529  // This reformatting is also implied by any other modifications that use or
  1530  // rewrite the go.mod file. The only time this flag is needed is if no other
  1531  // flags are specified, as in 'go work edit -fmt'.
  1532  //
  1533  // The -use=path and -dropuse=path flags
  1534  // add and drop a use directive from the go.work file's set of module directories.
  1535  //
  1536  // The -replace=old[@v]=new[@v] flag adds a replacement of the given
  1537  // module path and version pair. If the @v in old@v is omitted, a
  1538  // replacement without a version on the left side is added, which applies
  1539  // to all versions of the old module path. If the @v in new@v is omitted,
  1540  // the new path should be a local module root directory, not a module
  1541  // path. Note that -replace overrides any redundant replacements for old[@v],
  1542  // so omitting @v will drop existing replacements for specific versions.
  1543  //
  1544  // The -dropreplace=old[@v] flag drops a replacement of the given
  1545  // module path and version pair. If the @v is omitted, a replacement without
  1546  // a version on the left side is dropped.
  1547  //
  1548  // The -use, -dropuse, -replace, and -dropreplace,
  1549  // editing flags may be repeated, and the changes are applied in the order given.
  1550  //
  1551  // The -go=version flag sets the expected Go language version.
  1552  //
  1553  // The -toolchain=name flag sets the Go toolchain to use.
  1554  //
  1555  // The -print flag prints the final go.work in its text format instead of
  1556  // writing it back to go.mod.
  1557  //
  1558  // The -json flag prints the final go.work file in JSON format instead of
  1559  // writing it back to go.mod. The JSON output corresponds to these Go types:
  1560  //
  1561  //	type GoWork struct {
  1562  //		Go        string
  1563  //		Toolchain string
  1564  //		Use       []Use
  1565  //		Replace   []Replace
  1566  //	}
  1567  //
  1568  //	type Use struct {
  1569  //		DiskPath   string
  1570  //		ModulePath string
  1571  //	}
  1572  //
  1573  //	type Replace struct {
  1574  //		Old Module
  1575  //		New Module
  1576  //	}
  1577  //
  1578  //	type Module struct {
  1579  //		Path    string
  1580  //		Version string
  1581  //	}
  1582  //
  1583  // See the workspaces reference at https://go.dev/ref/mod#workspaces
  1584  // for more information.
  1585  //
  1586  // # Initialize workspace file
  1587  //
  1588  // Usage:
  1589  //
  1590  //	go work init [moddirs]
  1591  //
  1592  // Init initializes and writes a new go.work file in the
  1593  // current directory, in effect creating a new workspace at the current
  1594  // directory.
  1595  //
  1596  // go work init optionally accepts paths to the workspace modules as
  1597  // arguments. If the argument is omitted, an empty workspace with no
  1598  // modules will be created.
  1599  //
  1600  // Each argument path is added to a use directive in the go.work file. The
  1601  // current go version will also be listed in the go.work file.
  1602  //
  1603  // See the workspaces reference at https://go.dev/ref/mod#workspaces
  1604  // for more information.
  1605  //
  1606  // # Sync workspace build list to modules
  1607  //
  1608  // Usage:
  1609  //
  1610  //	go work sync
  1611  //
  1612  // Sync syncs the workspace's build list back to the
  1613  // workspace's modules
  1614  //
  1615  // The workspace's build list is the set of versions of all the
  1616  // (transitive) dependency modules used to do builds in the workspace. go
  1617  // work sync generates that build list using the Minimal Version Selection
  1618  // algorithm, and then syncs those versions back to each of modules
  1619  // specified in the workspace (with use directives).
  1620  //
  1621  // The syncing is done by sequentially upgrading each of the dependency
  1622  // modules specified in a workspace module to the version in the build list
  1623  // if the dependency module's version is not already the same as the build
  1624  // list's version. Note that Minimal Version Selection guarantees that the
  1625  // build list's version of each module is always the same or higher than
  1626  // that in each workspace module.
  1627  //
  1628  // See the workspaces reference at https://go.dev/ref/mod#workspaces
  1629  // for more information.
  1630  //
  1631  // # Add modules to workspace file
  1632  //
  1633  // Usage:
  1634  //
  1635  //	go work use [-r] [moddirs]
  1636  //
  1637  // Use provides a command-line interface for adding
  1638  // directories, optionally recursively, to a go.work file.
  1639  //
  1640  // A use directive will be added to the go.work file for each argument
  1641  // directory listed on the command line go.work file, if it exists,
  1642  // or removed from the go.work file if it does not exist.
  1643  // Use fails if any remaining use directives refer to modules that
  1644  // do not exist.
  1645  //
  1646  // Use updates the go line in go.work to specify a version at least as
  1647  // new as all the go lines in the used modules, both preexisting ones
  1648  // and newly added ones. With no arguments, this update is the only
  1649  // thing that go work use does.
  1650  //
  1651  // The -r flag searches recursively for modules in the argument
  1652  // directories, and the use command operates as if each of the directories
  1653  // were specified as arguments: namely, use directives will be added for
  1654  // directories that exist, and removed for directories that do not exist.
  1655  //
  1656  // See the workspaces reference at https://go.dev/ref/mod#workspaces
  1657  // for more information.
  1658  //
  1659  // # Make vendored copy of dependencies
  1660  //
  1661  // Usage:
  1662  //
  1663  //	go work vendor [-e] [-v] [-o outdir]
  1664  //
  1665  // Vendor resets the workspace's vendor directory to include all packages
  1666  // needed to build and test all the workspace's packages.
  1667  // It does not include test code for vendored packages.
  1668  //
  1669  // The -v flag causes vendor to print the names of vendored
  1670  // modules and packages to standard error.
  1671  //
  1672  // The -e flag causes vendor to attempt to proceed despite errors
  1673  // encountered while loading packages.
  1674  //
  1675  // The -o flag causes vendor to create the vendor directory at the given
  1676  // path instead of "vendor". The go command can only use a vendor directory
  1677  // named "vendor" within the module root directory, so this flag is
  1678  // primarily useful for other tools.
  1679  //
  1680  // # Compile and run Go program
  1681  //
  1682  // Usage:
  1683  //
  1684  //	go run [build flags] [-exec xprog] package [arguments...]
  1685  //
  1686  // Run compiles and runs the named main Go package.
  1687  // Typically the package is specified as a list of .go source files from a single
  1688  // directory, but it may also be an import path, file system path, or pattern
  1689  // matching a single known package, as in 'go run .' or 'go run my/cmd'.
  1690  //
  1691  // If the package argument has a version suffix (like @latest or @v1.0.0),
  1692  // "go run" builds the program in module-aware mode, ignoring the go.mod file in
  1693  // the current directory or any parent directory, if there is one. This is useful
  1694  // for running programs without affecting the dependencies of the main module.
  1695  //
  1696  // If the package argument doesn't have a version suffix, "go run" may run in
  1697  // module-aware mode or GOPATH mode, depending on the GO111MODULE environment
  1698  // variable and the presence of a go.mod file. See 'go help modules' for details.
  1699  // If module-aware mode is enabled, "go run" runs in the context of the main
  1700  // module.
  1701  //
  1702  // By default, 'go run' runs the compiled binary directly: 'a.out arguments...'.
  1703  // If the -exec flag is given, 'go run' invokes the binary using xprog:
  1704  //
  1705  //	'xprog a.out arguments...'.
  1706  //
  1707  // If the -exec flag is not given, GOOS or GOARCH is different from the system
  1708  // default, and a program named go_$GOOS_$GOARCH_exec can be found
  1709  // on the current search path, 'go run' invokes the binary using that program,
  1710  // for example 'go_js_wasm_exec a.out arguments...'. This allows execution of
  1711  // cross-compiled programs when a simulator or other execution method is
  1712  // available.
  1713  //
  1714  // By default, 'go run' compiles the binary without generating the information
  1715  // used by debuggers, to reduce build time. To include debugger information in
  1716  // the binary, use 'go build'.
  1717  //
  1718  // The exit status of Run is not the exit status of the compiled binary.
  1719  //
  1720  // For more about build flags, see 'go help build'.
  1721  // For more about specifying packages, see 'go help packages'.
  1722  //
  1723  // See also: go build.
  1724  //
  1725  // # Test packages
  1726  //
  1727  // Usage:
  1728  //
  1729  //	go test [build/test flags] [packages] [build/test flags & test binary flags]
  1730  //
  1731  // 'Go test' automates testing the packages named by the import paths.
  1732  // It prints a summary of the test results in the format:
  1733  //
  1734  //	ok   archive/tar   0.011s
  1735  //	FAIL archive/zip   0.022s
  1736  //	ok   compress/gzip 0.033s
  1737  //	...
  1738  //
  1739  // followed by detailed output for each failed package.
  1740  //
  1741  // 'Go test' recompiles each package along with any files with names matching
  1742  // the file pattern "*_test.go".
  1743  // These additional files can contain test functions, benchmark functions, fuzz
  1744  // tests and example functions. See 'go help testfunc' for more.
  1745  // Each listed package causes the execution of a separate test binary.
  1746  // Files whose names begin with "_" (including "_test.go") or "." are ignored.
  1747  //
  1748  // Test files that declare a package with the suffix "_test" will be compiled as a
  1749  // separate package, and then linked and run with the main test binary.
  1750  //
  1751  // The go tool will ignore a directory named "testdata", making it available
  1752  // to hold ancillary data needed by the tests.
  1753  //
  1754  // As part of building a test binary, go test runs go vet on the package
  1755  // and its test source files to identify significant problems. If go vet
  1756  // finds any problems, go test reports those and does not run the test
  1757  // binary. Only a high-confidence subset of the default go vet checks are
  1758  // used. That subset is: atomic, bool, buildtags, directive, errorsas,
  1759  // ifaceassert, nilfunc, printf, and stringintconv. You can see
  1760  // the documentation for these and other vet tests via "go doc cmd/vet".
  1761  // To disable the running of go vet, use the -vet=off flag. To run all
  1762  // checks, use the -vet=all flag.
  1763  //
  1764  // All test output and summary lines are printed to the go command's
  1765  // standard output, even if the test printed them to its own standard
  1766  // error. (The go command's standard error is reserved for printing
  1767  // errors building the tests.)
  1768  //
  1769  // The go command places $GOROOT/bin at the beginning of $PATH
  1770  // in the test's environment, so that tests that execute
  1771  // 'go' commands use the same 'go' as the parent 'go test' command.
  1772  //
  1773  // Go test runs in two different modes:
  1774  //
  1775  // The first, called local directory mode, occurs when go test is
  1776  // invoked with no package arguments (for example, 'go test' or 'go
  1777  // test -v'). In this mode, go test compiles the package sources and
  1778  // tests found in the current directory and then runs the resulting
  1779  // test binary. In this mode, caching (discussed below) is disabled.
  1780  // After the package test finishes, go test prints a summary line
  1781  // showing the test status ('ok' or 'FAIL'), package name, and elapsed
  1782  // time.
  1783  //
  1784  // The second, called package list mode, occurs when go test is invoked
  1785  // with explicit package arguments (for example 'go test math', 'go
  1786  // test ./...', and even 'go test .'). In this mode, go test compiles
  1787  // and tests each of the packages listed on the command line. If a
  1788  // package test passes, go test prints only the final 'ok' summary
  1789  // line. If a package test fails, go test prints the full test output.
  1790  // If invoked with the -bench or -v flag, go test prints the full
  1791  // output even for passing package tests, in order to display the
  1792  // requested benchmark results or verbose logging. After the package
  1793  // tests for all of the listed packages finish, and their output is
  1794  // printed, go test prints a final 'FAIL' status if any package test
  1795  // has failed.
  1796  //
  1797  // In package list mode only, go test caches successful package test
  1798  // results to avoid unnecessary repeated running of tests. When the
  1799  // result of a test can be recovered from the cache, go test will
  1800  // redisplay the previous output instead of running the test binary
  1801  // again. When this happens, go test prints '(cached)' in place of the
  1802  // elapsed time in the summary line.
  1803  //
  1804  // The rule for a match in the cache is that the run involves the same
  1805  // test binary and the flags on the command line come entirely from a
  1806  // restricted set of 'cacheable' test flags, defined as -benchtime, -cpu,
  1807  // -list, -parallel, -run, -short, -timeout, -failfast, -fullpath and -v.
  1808  // If a run of go test has any test or non-test flags outside this set,
  1809  // the result is not cached. To disable test caching, use any test flag
  1810  // or argument other than the cacheable flags. The idiomatic way to disable
  1811  // test caching explicitly is to use -count=1. Tests that open files within
  1812  // the package's source root (usually $GOPATH) or that consult environment
  1813  // variables only match future runs in which the files and environment
  1814  // variables are unchanged. A cached test result is treated as executing
  1815  // in no time at all, so a successful package test result will be cached and
  1816  // reused regardless of -timeout setting.
  1817  //
  1818  // In addition to the build flags, the flags handled by 'go test' itself are:
  1819  //
  1820  //	-args
  1821  //	    Pass the remainder of the command line (everything after -args)
  1822  //	    to the test binary, uninterpreted and unchanged.
  1823  //	    Because this flag consumes the remainder of the command line,
  1824  //	    the package list (if present) must appear before this flag.
  1825  //
  1826  //	-c
  1827  //	    Compile the test binary to pkg.test in the current directory but do not run it
  1828  //	    (where pkg is the last element of the package's import path).
  1829  //	    The file name or target directory can be changed with the -o flag.
  1830  //
  1831  //	-exec xprog
  1832  //	    Run the test binary using xprog. The behavior is the same as
  1833  //	    in 'go run'. See 'go help run' for details.
  1834  //
  1835  //	-json
  1836  //	    Convert test output to JSON suitable for automated processing.
  1837  //	    See 'go doc test2json' for the encoding details.
  1838  //
  1839  //	-o file
  1840  //	    Compile the test binary to the named file.
  1841  //	    The test still runs (unless -c or -i is specified).
  1842  //	    If file ends in a slash or names an existing directory,
  1843  //	    the test is written to pkg.test in that directory.
  1844  //
  1845  // The test binary also accepts flags that control execution of the test; these
  1846  // flags are also accessible by 'go test'. See 'go help testflag' for details.
  1847  //
  1848  // For more about build flags, see 'go help build'.
  1849  // For more about specifying packages, see 'go help packages'.
  1850  //
  1851  // See also: go build, go vet.
  1852  //
  1853  // # Run specified go tool
  1854  //
  1855  // Usage:
  1856  //
  1857  //	go tool [-n] command [args...]
  1858  //
  1859  // Tool runs the go tool command identified by the arguments.
  1860  // With no arguments it prints the list of known tools.
  1861  //
  1862  // The -n flag causes tool to print the command that would be
  1863  // executed but not execute it.
  1864  //
  1865  // For more about each tool command, see 'go doc cmd/<command>'.
  1866  //
  1867  // # Print Go version
  1868  //
  1869  // Usage:
  1870  //
  1871  //	go version [-m] [-v] [file ...]
  1872  //
  1873  // Version prints the build information for Go binary files.
  1874  //
  1875  // Go version reports the Go version used to build each of the named files.
  1876  //
  1877  // If no files are named on the command line, go version prints its own
  1878  // version information.
  1879  //
  1880  // If a directory is named, go version walks that directory, recursively,
  1881  // looking for recognized Go binaries and reporting their versions.
  1882  // By default, go version does not report unrecognized files found
  1883  // during a directory scan. The -v flag causes it to report unrecognized files.
  1884  //
  1885  // The -m flag causes go version to print each file's embedded
  1886  // module version information, when available. In the output, the module
  1887  // information consists of multiple lines following the version line, each
  1888  // indented by a leading tab character.
  1889  //
  1890  // See also: go doc runtime/debug.BuildInfo.
  1891  //
  1892  // # Report likely mistakes in packages
  1893  //
  1894  // Usage:
  1895  //
  1896  //	go vet [build flags] [-vettool prog] [vet flags] [packages]
  1897  //
  1898  // Vet runs the Go vet command on the packages named by the import paths.
  1899  //
  1900  // For more about vet and its flags, see 'go doc cmd/vet'.
  1901  // For more about specifying packages, see 'go help packages'.
  1902  // For a list of checkers and their flags, see 'go tool vet help'.
  1903  // For details of a specific checker such as 'printf', see 'go tool vet help printf'.
  1904  //
  1905  // The -vettool=prog flag selects a different analysis tool with alternative
  1906  // or additional checks.
  1907  // For example, the 'shadow' analyzer can be built and run using these commands:
  1908  //
  1909  //	go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow@latest
  1910  //	go vet -vettool=$(which shadow)
  1911  //
  1912  // The build flags supported by go vet are those that control package resolution
  1913  // and execution, such as -C, -n, -x, -v, -tags, and -toolexec.
  1914  // For more about these flags, see 'go help build'.
  1915  //
  1916  // See also: go fmt, go fix.
  1917  //
  1918  // # Build constraints
  1919  //
  1920  // A build constraint, also known as a build tag, is a condition under which a
  1921  // file should be included in the package. Build constraints are given by a
  1922  // line comment that begins
  1923  //
  1924  //	//go:build
  1925  //
  1926  // Constraints may appear in any kind of source file (not just Go), but
  1927  // they must appear near the top of the file, preceded
  1928  // only by blank lines and other comments. These rules mean that in Go
  1929  // files a build constraint must appear before the package clause.
  1930  //
  1931  // To distinguish build constraints from package documentation,
  1932  // a build constraint should be followed by a blank line.
  1933  //
  1934  // A build constraint comment is evaluated as an expression containing
  1935  // build tags combined by ||, &&, and ! operators and parentheses.
  1936  // Operators have the same meaning as in Go.
  1937  //
  1938  // For example, the following build constraint constrains a file to
  1939  // build when the "linux" and "386" constraints are satisfied, or when
  1940  // "darwin" is satisfied and "cgo" is not:
  1941  //
  1942  //	//go:build (linux && 386) || (darwin && !cgo)
  1943  //
  1944  // It is an error for a file to have more than one //go:build line.
  1945  //
  1946  // During a particular build, the following build tags are satisfied:
  1947  //
  1948  //   - the target operating system, as spelled by runtime.GOOS, set with the
  1949  //     GOOS environment variable.
  1950  //   - the target architecture, as spelled by runtime.GOARCH, set with the
  1951  //     GOARCH environment variable.
  1952  //   - any architecture features, in the form GOARCH.feature
  1953  //     (for example, "amd64.v2"), as detailed below.
  1954  //   - "unix", if GOOS is a Unix or Unix-like system.
  1955  //   - the compiler being used, either "gc" or "gccgo"
  1956  //   - "cgo", if the cgo command is supported (see CGO_ENABLED in
  1957  //     'go help environment').
  1958  //   - a term for each Go major release, through the current version:
  1959  //     "go1.1" from Go version 1.1 onward, "go1.12" from Go 1.12, and so on.
  1960  //   - any additional tags given by the -tags flag (see 'go help build').
  1961  //
  1962  // There are no separate build tags for beta or minor releases.
  1963  //
  1964  // If a file's name, after stripping the extension and a possible _test suffix,
  1965  // matches any of the following patterns:
  1966  //
  1967  //	*_GOOS
  1968  //	*_GOARCH
  1969  //	*_GOOS_GOARCH
  1970  //
  1971  // (example: source_windows_amd64.go) where GOOS and GOARCH represent
  1972  // any known operating system and architecture values respectively, then
  1973  // the file is considered to have an implicit build constraint requiring
  1974  // those terms (in addition to any explicit constraints in the file).
  1975  //
  1976  // Using GOOS=android matches build tags and files as for GOOS=linux
  1977  // in addition to android tags and files.
  1978  //
  1979  // Using GOOS=illumos matches build tags and files as for GOOS=solaris
  1980  // in addition to illumos tags and files.
  1981  //
  1982  // Using GOOS=ios matches build tags and files as for GOOS=darwin
  1983  // in addition to ios tags and files.
  1984  //
  1985  // The defined architecture feature build tags are:
  1986  //
  1987  //   - For GOARCH=386, GO386=387 and GO386=sse2
  1988  //     set the 386.387 and 386.sse2 build tags, respectively.
  1989  //   - For GOARCH=amd64, GOAMD64=v1, v2, and v3
  1990  //     correspond to the amd64.v1, amd64.v2, and amd64.v3 feature build tags.
  1991  //   - For GOARCH=arm, GOARM=5, 6, and 7
  1992  //     correspond to the arm.5, arm.6, and arm.7 feature build tags.
  1993  //   - For GOARCH=arm64, GOARM64=v8.{0-9} and v9.{0-5}
  1994  //     correspond to the arm64.v8.{0-9} and arm64.v9.{0-5} feature build tags.
  1995  //   - For GOARCH=mips or mipsle,
  1996  //     GOMIPS=hardfloat and softfloat
  1997  //     correspond to the mips.hardfloat and mips.softfloat
  1998  //     (or mipsle.hardfloat and mipsle.softfloat) feature build tags.
  1999  //   - For GOARCH=mips64 or mips64le,
  2000  //     GOMIPS64=hardfloat and softfloat
  2001  //     correspond to the mips64.hardfloat and mips64.softfloat
  2002  //     (or mips64le.hardfloat and mips64le.softfloat) feature build tags.
  2003  //   - For GOARCH=ppc64 or ppc64le,
  2004  //     GOPPC64=power8, power9, and power10 correspond to the
  2005  //     ppc64.power8, ppc64.power9, and ppc64.power10
  2006  //     (or ppc64le.power8, ppc64le.power9, and ppc64le.power10)
  2007  //     feature build tags.
  2008  //   - For GOARCH=riscv64,
  2009  //     GORISCV64=rva20u64 and rva22u64 correspond to the riscv64.rva20u64
  2010  //     and riscv64.rva22u64 build tags.
  2011  //   - For GOARCH=wasm, GOWASM=satconv and signext
  2012  //     correspond to the wasm.satconv and wasm.signext feature build tags.
  2013  //
  2014  // For GOARCH=amd64, arm, ppc64, ppc64le, and riscv64, a particular feature level
  2015  // sets the feature build tags for all previous levels as well.
  2016  // For example, GOAMD64=v2 sets the amd64.v1 and amd64.v2 feature flags.
  2017  // This ensures that code making use of v2 features continues to compile
  2018  // when, say, GOAMD64=v4 is introduced.
  2019  // Code handling the absence of a particular feature level
  2020  // should use a negation:
  2021  //
  2022  //	//go:build !amd64.v2
  2023  //
  2024  // To keep a file from being considered for any build:
  2025  //
  2026  //	//go:build ignore
  2027  //
  2028  // (Any other unsatisfied word will work as well, but "ignore" is conventional.)
  2029  //
  2030  // To build a file only when using cgo, and only on Linux and OS X:
  2031  //
  2032  //	//go:build cgo && (linux || darwin)
  2033  //
  2034  // Such a file is usually paired with another file implementing the
  2035  // default functionality for other systems, which in this case would
  2036  // carry the constraint:
  2037  //
  2038  //	//go:build !(cgo && (linux || darwin))
  2039  //
  2040  // Naming a file dns_windows.go will cause it to be included only when
  2041  // building the package for Windows; similarly, math_386.s will be included
  2042  // only when building the package for 32-bit x86.
  2043  //
  2044  // Go versions 1.16 and earlier used a different syntax for build constraints,
  2045  // with a "// +build" prefix. The gofmt command will add an equivalent //go:build
  2046  // constraint when encountering the older syntax.
  2047  //
  2048  // # Build modes
  2049  //
  2050  // The 'go build' and 'go install' commands take a -buildmode argument which
  2051  // indicates which kind of object file is to be built. Currently supported values
  2052  // are:
  2053  //
  2054  //	-buildmode=archive
  2055  //		Build the listed non-main packages into .a files. Packages named
  2056  //		main are ignored.
  2057  //
  2058  //	-buildmode=c-archive
  2059  //		Build the listed main package, plus all packages it imports,
  2060  //		into a C archive file. The only callable symbols will be those
  2061  //		functions exported using a cgo //export comment. Requires
  2062  //		exactly one main package to be listed.
  2063  //
  2064  //	-buildmode=c-shared
  2065  //		Build the listed main package, plus all packages it imports,
  2066  //		into a C shared library. The only callable symbols will
  2067  //		be those functions exported using a cgo //export comment.
  2068  //		Requires exactly one main package to be listed.
  2069  //
  2070  //	-buildmode=default
  2071  //		Listed main packages are built into executables and listed
  2072  //		non-main packages are built into .a files (the default
  2073  //		behavior).
  2074  //
  2075  //	-buildmode=shared
  2076  //		Combine all the listed non-main packages into a single shared
  2077  //		library that will be used when building with the -linkshared
  2078  //		option. Packages named main are ignored.
  2079  //
  2080  //	-buildmode=exe
  2081  //		Build the listed main packages and everything they import into
  2082  //		executables. Packages not named main are ignored.
  2083  //
  2084  //	-buildmode=pie
  2085  //		Build the listed main packages and everything they import into
  2086  //		position independent executables (PIE). Packages not named
  2087  //		main are ignored.
  2088  //
  2089  //	-buildmode=plugin
  2090  //		Build the listed main packages, plus all packages that they
  2091  //		import, into a Go plugin. Packages not named main are ignored.
  2092  //
  2093  // On AIX, when linking a C program that uses a Go archive built with
  2094  // -buildmode=c-archive, you must pass -Wl,-bnoobjreorder to the C compiler.
  2095  //
  2096  // # Calling between Go and C
  2097  //
  2098  // There are two different ways to call between Go and C/C++ code.
  2099  //
  2100  // The first is the cgo tool, which is part of the Go distribution. For
  2101  // information on how to use it see the cgo documentation (go doc cmd/cgo).
  2102  //
  2103  // The second is the SWIG program, which is a general tool for
  2104  // interfacing between languages. For information on SWIG see
  2105  // http://swig.org/. When running go build, any file with a .swig
  2106  // extension will be passed to SWIG. Any file with a .swigcxx extension
  2107  // will be passed to SWIG with the -c++ option.
  2108  //
  2109  // When either cgo or SWIG is used, go build will pass any .c, .m, .s, .S
  2110  // or .sx files to the C compiler, and any .cc, .cpp, .cxx files to the C++
  2111  // compiler. The CC or CXX environment variables may be set to determine
  2112  // the C or C++ compiler, respectively, to use.
  2113  //
  2114  // # Build and test caching
  2115  //
  2116  // The go command caches build outputs for reuse in future builds.
  2117  // The default location for cache data is a subdirectory named go-build
  2118  // in the standard user cache directory for the current operating system.
  2119  // Setting the GOCACHE environment variable overrides this default,
  2120  // and running 'go env GOCACHE' prints the current cache directory.
  2121  //
  2122  // The go command periodically deletes cached data that has not been
  2123  // used recently. Running 'go clean -cache' deletes all cached data.
  2124  //
  2125  // The build cache correctly accounts for changes to Go source files,
  2126  // compilers, compiler options, and so on: cleaning the cache explicitly
  2127  // should not be necessary in typical use. However, the build cache
  2128  // does not detect changes to C libraries imported with cgo.
  2129  // If you have made changes to the C libraries on your system, you
  2130  // will need to clean the cache explicitly or else use the -a build flag
  2131  // (see 'go help build') to force rebuilding of packages that
  2132  // depend on the updated C libraries.
  2133  //
  2134  // The go command also caches successful package test results.
  2135  // See 'go help test' for details. Running 'go clean -testcache' removes
  2136  // all cached test results (but not cached build results).
  2137  //
  2138  // The go command also caches values used in fuzzing with 'go test -fuzz',
  2139  // specifically, values that expanded code coverage when passed to a
  2140  // fuzz function. These values are not used for regular building and
  2141  // testing, but they're stored in a subdirectory of the build cache.
  2142  // Running 'go clean -fuzzcache' removes all cached fuzzing values.
  2143  // This may make fuzzing less effective, temporarily.
  2144  //
  2145  // The GODEBUG environment variable can enable printing of debugging
  2146  // information about the state of the cache:
  2147  //
  2148  // GODEBUG=gocacheverify=1 causes the go command to bypass the
  2149  // use of any cache entries and instead rebuild everything and check
  2150  // that the results match existing cache entries.
  2151  //
  2152  // GODEBUG=gocachehash=1 causes the go command to print the inputs
  2153  // for all of the content hashes it uses to construct cache lookup keys.
  2154  // The output is voluminous but can be useful for debugging the cache.
  2155  //
  2156  // GODEBUG=gocachetest=1 causes the go command to print details of its
  2157  // decisions about whether to reuse a cached test result.
  2158  //
  2159  // # Environment variables
  2160  //
  2161  // The go command and the tools it invokes consult environment variables
  2162  // for configuration. If an environment variable is unset or empty, the go
  2163  // command uses a sensible default setting. To see the effective setting of
  2164  // the variable <NAME>, run 'go env <NAME>'. To change the default setting,
  2165  // run 'go env -w <NAME>=<VALUE>'. Defaults changed using 'go env -w'
  2166  // are recorded in a Go environment configuration file stored in the
  2167  // per-user configuration directory, as reported by os.UserConfigDir.
  2168  // The location of the configuration file can be changed by setting
  2169  // the environment variable GOENV, and 'go env GOENV' prints the
  2170  // effective location, but 'go env -w' cannot change the default location.
  2171  // See 'go help env' for details.
  2172  //
  2173  // General-purpose environment variables:
  2174  //
  2175  //	GO111MODULE
  2176  //		Controls whether the go command runs in module-aware mode or GOPATH mode.
  2177  //		May be "off", "on", or "auto".
  2178  //		See https://golang.org/ref/mod#mod-commands.
  2179  //	GCCGO
  2180  //		The gccgo command to run for 'go build -compiler=gccgo'.
  2181  //	GOARCH
  2182  //		The architecture, or processor, for which to compile code.
  2183  //		Examples are amd64, 386, arm, ppc64.
  2184  //	GOBIN
  2185  //		The directory where 'go install' will install a command.
  2186  //	GOCACHE
  2187  //		The directory where the go command will store cached
  2188  //		information for reuse in future builds.
  2189  //	GOMODCACHE
  2190  //		The directory where the go command will store downloaded modules.
  2191  //	GODEBUG
  2192  //		Enable various debugging facilities. See https://go.dev/doc/godebug
  2193  //		for details.
  2194  //	GOENV
  2195  //		The location of the Go environment configuration file.
  2196  //		Cannot be set using 'go env -w'.
  2197  //		Setting GOENV=off in the environment disables the use of the
  2198  //		default configuration file.
  2199  //	GOFLAGS
  2200  //		A space-separated list of -flag=value settings to apply
  2201  //		to go commands by default, when the given flag is known by
  2202  //		the current command. Each entry must be a standalone flag.
  2203  //		Because the entries are space-separated, flag values must
  2204  //		not contain spaces. Flags listed on the command line
  2205  //		are applied after this list and therefore override it.
  2206  //	GOINSECURE
  2207  //		Comma-separated list of glob patterns (in the syntax of Go's path.Match)
  2208  //		of module path prefixes that should always be fetched in an insecure
  2209  //		manner. Only applies to dependencies that are being fetched directly.
  2210  //		GOINSECURE does not disable checksum database validation. GOPRIVATE or
  2211  //		GONOSUMDB may be used to achieve that.
  2212  //	GOOS
  2213  //		The operating system for which to compile code.
  2214  //		Examples are linux, darwin, windows, netbsd.
  2215  //	GOPATH
  2216  //		Controls where various files are stored. See: 'go help gopath'.
  2217  //	GOPROXY
  2218  //		URL of Go module proxy. See https://golang.org/ref/mod#environment-variables
  2219  //		and https://golang.org/ref/mod#module-proxy for details.
  2220  //	GOPRIVATE, GONOPROXY, GONOSUMDB
  2221  //		Comma-separated list of glob patterns (in the syntax of Go's path.Match)
  2222  //		of module path prefixes that should always be fetched directly
  2223  //		or that should not be compared against the checksum database.
  2224  //		See https://golang.org/ref/mod#private-modules.
  2225  //	GOROOT
  2226  //		The root of the go tree.
  2227  //	GOSUMDB
  2228  //		The name of checksum database to use and optionally its public key and
  2229  //		URL. See https://golang.org/ref/mod#authenticating.
  2230  //	GOTOOLCHAIN
  2231  //		Controls which Go toolchain is used. See https://go.dev/doc/toolchain.
  2232  //	GOTMPDIR
  2233  //		The directory where the go command will write
  2234  //		temporary source files, packages, and binaries.
  2235  //	GOVCS
  2236  //		Lists version control commands that may be used with matching servers.
  2237  //		See 'go help vcs'.
  2238  //	GOWORK
  2239  //		In module aware mode, use the given go.work file as a workspace file.
  2240  //		By default or when GOWORK is "auto", the go command searches for a
  2241  //		file named go.work in the current directory and then containing directories
  2242  //		until one is found. If a valid go.work file is found, the modules
  2243  //		specified will collectively be used as the main modules. If GOWORK
  2244  //		is "off", or a go.work file is not found in "auto" mode, workspace
  2245  //		mode is disabled.
  2246  //
  2247  // Environment variables for use with cgo:
  2248  //
  2249  //	AR
  2250  //		The command to use to manipulate library archives when
  2251  //		building with the gccgo compiler.
  2252  //		The default is 'ar'.
  2253  //	CC
  2254  //		The command to use to compile C code.
  2255  //	CGO_ENABLED
  2256  //		Whether the cgo command is supported. Either 0 or 1.
  2257  //	CGO_CFLAGS
  2258  //		Flags that cgo will pass to the compiler when compiling
  2259  //		C code.
  2260  //	CGO_CFLAGS_ALLOW
  2261  //		A regular expression specifying additional flags to allow
  2262  //		to appear in #cgo CFLAGS source code directives.
  2263  //		Does not apply to the CGO_CFLAGS environment variable.
  2264  //	CGO_CFLAGS_DISALLOW
  2265  //		A regular expression specifying flags that must be disallowed
  2266  //		from appearing in #cgo CFLAGS source code directives.
  2267  //		Does not apply to the CGO_CFLAGS environment variable.
  2268  //	CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
  2269  //		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  2270  //		but for the C preprocessor.
  2271  //	CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
  2272  //		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  2273  //		but for the C++ compiler.
  2274  //	CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
  2275  //		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  2276  //		but for the Fortran compiler.
  2277  //	CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
  2278  //		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  2279  //		but for the linker.
  2280  //	CXX
  2281  //		The command to use to compile C++ code.
  2282  //	FC
  2283  //		The command to use to compile Fortran code.
  2284  //	PKG_CONFIG
  2285  //		Path to pkg-config tool.
  2286  //
  2287  // Architecture-specific environment variables:
  2288  //
  2289  //	GOARM
  2290  //		For GOARCH=arm, the ARM architecture for which to compile.
  2291  //		Valid values are 5, 6, 7.
  2292  //		The value can be followed by an option specifying how to implement floating point instructions.
  2293  //		Valid options are ,softfloat (default for 5) and ,hardfloat (default for 6 and 7).
  2294  //	GOARM64
  2295  //		For GOARCH=arm64, the ARM64 architecture for which to compile.
  2296  //		Valid values are v8.0 (default), v8.{1-9}, v9.{0-5}.
  2297  //		The value can be followed by an option specifying extensions implemented by target hardware.
  2298  //		Valid options are ,lse and ,crypto.
  2299  //		Note that some extensions are enabled by default starting from a certain GOARM64 version;
  2300  //		for example, lse is enabled by default starting from v8.1.
  2301  //	GO386
  2302  //		For GOARCH=386, how to implement floating point instructions.
  2303  //		Valid values are sse2 (default), softfloat.
  2304  //	GOAMD64
  2305  //		For GOARCH=amd64, the microarchitecture level for which to compile.
  2306  //		Valid values are v1 (default), v2, v3, v4.
  2307  //		See https://golang.org/wiki/MinimumRequirements#amd64
  2308  //	GOMIPS
  2309  //		For GOARCH=mips{,le}, whether to use floating point instructions.
  2310  //		Valid values are hardfloat (default), softfloat.
  2311  //	GOMIPS64
  2312  //		For GOARCH=mips64{,le}, whether to use floating point instructions.
  2313  //		Valid values are hardfloat (default), softfloat.
  2314  //	GOPPC64
  2315  //		For GOARCH=ppc64{,le}, the target ISA (Instruction Set Architecture).
  2316  //		Valid values are power8 (default), power9, power10.
  2317  //	GORISCV64
  2318  //		For GOARCH=riscv64, the RISC-V user-mode application profile for which
  2319  //		to compile. Valid values are rva20u64 (default), rva22u64.
  2320  //		See https://github.com/riscv/riscv-profiles/blob/main/profiles.adoc
  2321  //	GOWASM
  2322  //		For GOARCH=wasm, comma-separated list of experimental WebAssembly features to use.
  2323  //		Valid values are satconv, signext.
  2324  //
  2325  // Environment variables for use with code coverage:
  2326  //
  2327  //	GOCOVERDIR
  2328  //		Directory into which to write code coverage data files
  2329  //		generated by running a "go build -cover" binary.
  2330  //		Requires that GOEXPERIMENT=coverageredesign is enabled.
  2331  //
  2332  // Special-purpose environment variables:
  2333  //
  2334  //	GCCGOTOOLDIR
  2335  //		If set, where to find gccgo tools, such as cgo.
  2336  //		The default is based on how gccgo was configured.
  2337  //	GOEXPERIMENT
  2338  //		Comma-separated list of toolchain experiments to enable or disable.
  2339  //		The list of available experiments may change arbitrarily over time.
  2340  //		See src/internal/goexperiment/flags.go for currently valid values.
  2341  //		Warning: This variable is provided for the development and testing
  2342  //		of the Go toolchain itself. Use beyond that purpose is unsupported.
  2343  //	GO_EXTLINK_ENABLED
  2344  //		Whether the linker should use external linking mode
  2345  //		when using -linkmode=auto with code that uses cgo.
  2346  //		Set to 0 to disable external linking mode, 1 to enable it.
  2347  //	GIT_ALLOW_PROTOCOL
  2348  //		Defined by Git. A colon-separated list of schemes that are allowed
  2349  //		to be used with git fetch/clone. If set, any scheme not explicitly
  2350  //		mentioned will be considered insecure by 'go get'.
  2351  //		Because the variable is defined by Git, the default value cannot
  2352  //		be set using 'go env -w'.
  2353  //
  2354  // Additional information available from 'go env' but not read from the environment:
  2355  //
  2356  //	GOEXE
  2357  //		The executable file name suffix (".exe" on Windows, "" on other systems).
  2358  //	GOGCCFLAGS
  2359  //		A space-separated list of arguments supplied to the CC command.
  2360  //	GOHOSTARCH
  2361  //		The architecture (GOARCH) of the Go toolchain binaries.
  2362  //	GOHOSTOS
  2363  //		The operating system (GOOS) of the Go toolchain binaries.
  2364  //	GOMOD
  2365  //		The absolute path to the go.mod of the main module.
  2366  //		If module-aware mode is enabled, but there is no go.mod, GOMOD will be
  2367  //		os.DevNull ("/dev/null" on Unix-like systems, "NUL" on Windows).
  2368  //		If module-aware mode is disabled, GOMOD will be the empty string.
  2369  //	GOTOOLDIR
  2370  //		The directory where the go tools (compile, cover, doc, etc...) are installed.
  2371  //	GOVERSION
  2372  //		The version of the installed Go tree, as reported by runtime.Version.
  2373  //
  2374  // # File types
  2375  //
  2376  // The go command examines the contents of a restricted set of files
  2377  // in each directory. It identifies which files to examine based on
  2378  // the extension of the file name. These extensions are:
  2379  //
  2380  //	.go
  2381  //		Go source files.
  2382  //	.c, .h
  2383  //		C source files.
  2384  //		If the package uses cgo or SWIG, these will be compiled with the
  2385  //		OS-native compiler (typically gcc); otherwise they will
  2386  //		trigger an error.
  2387  //	.cc, .cpp, .cxx, .hh, .hpp, .hxx
  2388  //		C++ source files. Only useful with cgo or SWIG, and always
  2389  //		compiled with the OS-native compiler.
  2390  //	.m
  2391  //		Objective-C source files. Only useful with cgo, and always
  2392  //		compiled with the OS-native compiler.
  2393  //	.s, .S, .sx
  2394  //		Assembler source files.
  2395  //		If the package uses cgo or SWIG, these will be assembled with the
  2396  //		OS-native assembler (typically gcc (sic)); otherwise they
  2397  //		will be assembled with the Go assembler.
  2398  //	.swig, .swigcxx
  2399  //		SWIG definition files.
  2400  //	.syso
  2401  //		System object files.
  2402  //
  2403  // Files of each of these types except .syso may contain build
  2404  // constraints, but the go command stops scanning for build constraints
  2405  // at the first item in the file that is not a blank line or //-style
  2406  // line comment. See the go/build package documentation for
  2407  // more details.
  2408  //
  2409  // # The go.mod file
  2410  //
  2411  // A module version is defined by a tree of source files, with a go.mod
  2412  // file in its root. When the go command is run, it looks in the current
  2413  // directory and then successive parent directories to find the go.mod
  2414  // marking the root of the main (current) module.
  2415  //
  2416  // The go.mod file format is described in detail at
  2417  // https://golang.org/ref/mod#go-mod-file.
  2418  //
  2419  // To create a new go.mod file, use 'go mod init'. For details see
  2420  // 'go help mod init' or https://golang.org/ref/mod#go-mod-init.
  2421  //
  2422  // To add missing module requirements or remove unneeded requirements,
  2423  // use 'go mod tidy'. For details, see 'go help mod tidy' or
  2424  // https://golang.org/ref/mod#go-mod-tidy.
  2425  //
  2426  // To add, upgrade, downgrade, or remove a specific module requirement, use
  2427  // 'go get'. For details, see 'go help module-get' or
  2428  // https://golang.org/ref/mod#go-get.
  2429  //
  2430  // To make other changes or to parse go.mod as JSON for use by other tools,
  2431  // use 'go mod edit'. See 'go help mod edit' or
  2432  // https://golang.org/ref/mod#go-mod-edit.
  2433  //
  2434  // # GOPATH environment variable
  2435  //
  2436  // The Go path is used to resolve import statements.
  2437  // It is implemented by and documented in the go/build package.
  2438  //
  2439  // The GOPATH environment variable lists places to look for Go code.
  2440  // On Unix, the value is a colon-separated string.
  2441  // On Windows, the value is a semicolon-separated string.
  2442  // On Plan 9, the value is a list.
  2443  //
  2444  // If the environment variable is unset, GOPATH defaults
  2445  // to a subdirectory named "go" in the user's home directory
  2446  // ($HOME/go on Unix, %USERPROFILE%\go on Windows),
  2447  // unless that directory holds a Go distribution.
  2448  // Run "go env GOPATH" to see the current GOPATH.
  2449  //
  2450  // See https://golang.org/wiki/SettingGOPATH to set a custom GOPATH.
  2451  //
  2452  // Each directory listed in GOPATH must have a prescribed structure:
  2453  //
  2454  // The src directory holds source code. The path below src
  2455  // determines the import path or executable name.
  2456  //
  2457  // The pkg directory holds installed package objects.
  2458  // As in the Go tree, each target operating system and
  2459  // architecture pair has its own subdirectory of pkg
  2460  // (pkg/GOOS_GOARCH).
  2461  //
  2462  // If DIR is a directory listed in the GOPATH, a package with
  2463  // source in DIR/src/foo/bar can be imported as "foo/bar" and
  2464  // has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
  2465  //
  2466  // The bin directory holds compiled commands.
  2467  // Each command is named for its source directory, but only
  2468  // the final element, not the entire path. That is, the
  2469  // command with source in DIR/src/foo/quux is installed into
  2470  // DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped
  2471  // so that you can add DIR/bin to your PATH to get at the
  2472  // installed commands. If the GOBIN environment variable is
  2473  // set, commands are installed to the directory it names instead
  2474  // of DIR/bin. GOBIN must be an absolute path.
  2475  //
  2476  // Here's an example directory layout:
  2477  //
  2478  //	GOPATH=/home/user/go
  2479  //
  2480  //	/home/user/go/
  2481  //	    src/
  2482  //	        foo/
  2483  //	            bar/               (go code in package bar)
  2484  //	                x.go
  2485  //	            quux/              (go code in package main)
  2486  //	                y.go
  2487  //	    bin/
  2488  //	        quux                   (installed command)
  2489  //	    pkg/
  2490  //	        linux_amd64/
  2491  //	            foo/
  2492  //	                bar.a          (installed package object)
  2493  //
  2494  // Go searches each directory listed in GOPATH to find source code,
  2495  // but new packages are always downloaded into the first directory
  2496  // in the list.
  2497  //
  2498  // See https://golang.org/doc/code.html for an example.
  2499  //
  2500  // # GOPATH and Modules
  2501  //
  2502  // When using modules, GOPATH is no longer used for resolving imports.
  2503  // However, it is still used to store downloaded source code (in GOPATH/pkg/mod)
  2504  // and compiled commands (in GOPATH/bin).
  2505  //
  2506  // # Internal Directories
  2507  //
  2508  // Code in or below a directory named "internal" is importable only
  2509  // by code in the directory tree rooted at the parent of "internal".
  2510  // Here's an extended version of the directory layout above:
  2511  //
  2512  //	/home/user/go/
  2513  //	    src/
  2514  //	        crash/
  2515  //	            bang/              (go code in package bang)
  2516  //	                b.go
  2517  //	        foo/                   (go code in package foo)
  2518  //	            f.go
  2519  //	            bar/               (go code in package bar)
  2520  //	                x.go
  2521  //	            internal/
  2522  //	                baz/           (go code in package baz)
  2523  //	                    z.go
  2524  //	            quux/              (go code in package main)
  2525  //	                y.go
  2526  //
  2527  // The code in z.go is imported as "foo/internal/baz", but that
  2528  // import statement can only appear in source files in the subtree
  2529  // rooted at foo. The source files foo/f.go, foo/bar/x.go, and
  2530  // foo/quux/y.go can all import "foo/internal/baz", but the source file
  2531  // crash/bang/b.go cannot.
  2532  //
  2533  // See https://golang.org/s/go14internal for details.
  2534  //
  2535  // # Vendor Directories
  2536  //
  2537  // Go 1.6 includes support for using local copies of external dependencies
  2538  // to satisfy imports of those dependencies, often referred to as vendoring.
  2539  //
  2540  // Code below a directory named "vendor" is importable only
  2541  // by code in the directory tree rooted at the parent of "vendor",
  2542  // and only using an import path that omits the prefix up to and
  2543  // including the vendor element.
  2544  //
  2545  // Here's the example from the previous section,
  2546  // but with the "internal" directory renamed to "vendor"
  2547  // and a new foo/vendor/crash/bang directory added:
  2548  //
  2549  //	/home/user/go/
  2550  //	    src/
  2551  //	        crash/
  2552  //	            bang/              (go code in package bang)
  2553  //	                b.go
  2554  //	        foo/                   (go code in package foo)
  2555  //	            f.go
  2556  //	            bar/               (go code in package bar)
  2557  //	                x.go
  2558  //	            vendor/
  2559  //	                crash/
  2560  //	                    bang/      (go code in package bang)
  2561  //	                        b.go
  2562  //	                baz/           (go code in package baz)
  2563  //	                    z.go
  2564  //	            quux/              (go code in package main)
  2565  //	                y.go
  2566  //
  2567  // The same visibility rules apply as for internal, but the code
  2568  // in z.go is imported as "baz", not as "foo/vendor/baz".
  2569  //
  2570  // Code in vendor directories deeper in the source tree shadows
  2571  // code in higher directories. Within the subtree rooted at foo, an import
  2572  // of "crash/bang" resolves to "foo/vendor/crash/bang", not the
  2573  // top-level "crash/bang".
  2574  //
  2575  // Code in vendor directories is not subject to import path
  2576  // checking (see 'go help importpath').
  2577  //
  2578  // When 'go get' checks out or updates a git repository, it now also
  2579  // updates submodules.
  2580  //
  2581  // Vendor directories do not affect the placement of new repositories
  2582  // being checked out for the first time by 'go get': those are always
  2583  // placed in the main GOPATH, never in a vendor subtree.
  2584  //
  2585  // See https://golang.org/s/go15vendor for details.
  2586  //
  2587  // # Module proxy protocol
  2588  //
  2589  // A Go module proxy is any web server that can respond to GET requests for
  2590  // URLs of a specified form. The requests have no query parameters, so even
  2591  // a site serving from a fixed file system (including a file:/// URL)
  2592  // can be a module proxy.
  2593  //
  2594  // For details on the GOPROXY protocol, see
  2595  // https://golang.org/ref/mod#goproxy-protocol.
  2596  //
  2597  // # Import path syntax
  2598  //
  2599  // An import path (see 'go help packages') denotes a package stored in the local
  2600  // file system. In general, an import path denotes either a standard package (such
  2601  // as "unicode/utf8") or a package found in one of the work spaces (For more
  2602  // details see: 'go help gopath').
  2603  //
  2604  // # Relative import paths
  2605  //
  2606  // An import path beginning with ./ or ../ is called a relative path.
  2607  // The toolchain supports relative import paths as a shortcut in two ways.
  2608  //
  2609  // First, a relative path can be used as a shorthand on the command line.
  2610  // If you are working in the directory containing the code imported as
  2611  // "unicode" and want to run the tests for "unicode/utf8", you can type
  2612  // "go test ./utf8" instead of needing to specify the full path.
  2613  // Similarly, in the reverse situation, "go test .." will test "unicode" from
  2614  // the "unicode/utf8" directory. Relative patterns are also allowed, like
  2615  // "go test ./..." to test all subdirectories. See 'go help packages' for details
  2616  // on the pattern syntax.
  2617  //
  2618  // Second, if you are compiling a Go program not in a work space,
  2619  // you can use a relative path in an import statement in that program
  2620  // to refer to nearby code also not in a work space.
  2621  // This makes it easy to experiment with small multipackage programs
  2622  // outside of the usual work spaces, but such programs cannot be
  2623  // installed with "go install" (there is no work space in which to install them),
  2624  // so they are rebuilt from scratch each time they are built.
  2625  // To avoid ambiguity, Go programs cannot use relative import paths
  2626  // within a work space.
  2627  //
  2628  // # Remote import paths
  2629  //
  2630  // Certain import paths also
  2631  // describe how to obtain the source code for the package using
  2632  // a revision control system.
  2633  //
  2634  // A few common code hosting sites have special syntax:
  2635  //
  2636  //	Bitbucket (Git, Mercurial)
  2637  //
  2638  //		import "bitbucket.org/user/project"
  2639  //		import "bitbucket.org/user/project/sub/directory"
  2640  //
  2641  //	GitHub (Git)
  2642  //
  2643  //		import "github.com/user/project"
  2644  //		import "github.com/user/project/sub/directory"
  2645  //
  2646  //	Launchpad (Bazaar)
  2647  //
  2648  //		import "launchpad.net/project"
  2649  //		import "launchpad.net/project/series"
  2650  //		import "launchpad.net/project/series/sub/directory"
  2651  //
  2652  //		import "launchpad.net/~user/project/branch"
  2653  //		import "launchpad.net/~user/project/branch/sub/directory"
  2654  //
  2655  //	IBM DevOps Services (Git)
  2656  //
  2657  //		import "hub.jazz.net/git/user/project"
  2658  //		import "hub.jazz.net/git/user/project/sub/directory"
  2659  //
  2660  // For code hosted on other servers, import paths may either be qualified
  2661  // with the version control type, or the go tool can dynamically fetch
  2662  // the import path over https/http and discover where the code resides
  2663  // from a <meta> tag in the HTML.
  2664  //
  2665  // To declare the code location, an import path of the form
  2666  //
  2667  //	repository.vcs/path
  2668  //
  2669  // specifies the given repository, with or without the .vcs suffix,
  2670  // using the named version control system, and then the path inside
  2671  // that repository. The supported version control systems are:
  2672  //
  2673  //	Bazaar      .bzr
  2674  //	Fossil      .fossil
  2675  //	Git         .git
  2676  //	Mercurial   .hg
  2677  //	Subversion  .svn
  2678  //
  2679  // For example,
  2680  //
  2681  //	import "example.org/user/foo.hg"
  2682  //
  2683  // denotes the root directory of the Mercurial repository at
  2684  // example.org/user/foo or foo.hg, and
  2685  //
  2686  //	import "example.org/repo.git/foo/bar"
  2687  //
  2688  // denotes the foo/bar directory of the Git repository at
  2689  // example.org/repo or repo.git.
  2690  //
  2691  // When a version control system supports multiple protocols,
  2692  // each is tried in turn when downloading. For example, a Git
  2693  // download tries https://, then git+ssh://.
  2694  //
  2695  // By default, downloads are restricted to known secure protocols
  2696  // (e.g. https, ssh). To override this setting for Git downloads, the
  2697  // GIT_ALLOW_PROTOCOL environment variable can be set (For more details see:
  2698  // 'go help environment').
  2699  //
  2700  // If the import path is not a known code hosting site and also lacks a
  2701  // version control qualifier, the go tool attempts to fetch the import
  2702  // over https/http and looks for a <meta> tag in the document's HTML
  2703  // <head>.
  2704  //
  2705  // The meta tag has the form:
  2706  //
  2707  //	<meta name="go-import" content="import-prefix vcs repo-root">
  2708  //
  2709  // The import-prefix is the import path corresponding to the repository
  2710  // root. It must be a prefix or an exact match of the package being
  2711  // fetched with "go get". If it's not an exact match, another http
  2712  // request is made at the prefix to verify the <meta> tags match.
  2713  //
  2714  // The meta tag should appear as early in the file as possible.
  2715  // In particular, it should appear before any raw JavaScript or CSS,
  2716  // to avoid confusing the go command's restricted parser.
  2717  //
  2718  // The vcs is one of "bzr", "fossil", "git", "hg", "svn".
  2719  //
  2720  // The repo-root is the root of the version control system
  2721  // containing a scheme and not containing a .vcs qualifier.
  2722  //
  2723  // For example,
  2724  //
  2725  //	import "example.org/pkg/foo"
  2726  //
  2727  // will result in the following requests:
  2728  //
  2729  //	https://example.org/pkg/foo?go-get=1 (preferred)
  2730  //	http://example.org/pkg/foo?go-get=1  (fallback, only with use of correctly set GOINSECURE)
  2731  //
  2732  // If that page contains the meta tag
  2733  //
  2734  //	<meta name="go-import" content="example.org git https://code.org/r/p/exproj">
  2735  //
  2736  // the go tool will verify that https://example.org/?go-get=1 contains the
  2737  // same meta tag and then git clone https://code.org/r/p/exproj into
  2738  // GOPATH/src/example.org.
  2739  //
  2740  // When using GOPATH, downloaded packages are written to the first directory
  2741  // listed in the GOPATH environment variable.
  2742  // (See 'go help gopath-get' and 'go help gopath'.)
  2743  //
  2744  // When using modules, downloaded packages are stored in the module cache.
  2745  // See https://golang.org/ref/mod#module-cache.
  2746  //
  2747  // When using modules, an additional variant of the go-import meta tag is
  2748  // recognized and is preferred over those listing version control systems.
  2749  // That variant uses "mod" as the vcs in the content value, as in:
  2750  //
  2751  //	<meta name="go-import" content="example.org mod https://code.org/moduleproxy">
  2752  //
  2753  // This tag means to fetch modules with paths beginning with example.org
  2754  // from the module proxy available at the URL https://code.org/moduleproxy.
  2755  // See https://golang.org/ref/mod#goproxy-protocol for details about the
  2756  // proxy protocol.
  2757  //
  2758  // # Import path checking
  2759  //
  2760  // When the custom import path feature described above redirects to a
  2761  // known code hosting site, each of the resulting packages has two possible
  2762  // import paths, using the custom domain or the known hosting site.
  2763  //
  2764  // A package statement is said to have an "import comment" if it is immediately
  2765  // followed (before the next newline) by a comment of one of these two forms:
  2766  //
  2767  //	package math // import "path"
  2768  //	package math /* import "path" */
  2769  //
  2770  // The go command will refuse to install a package with an import comment
  2771  // unless it is being referred to by that import path. In this way, import comments
  2772  // let package authors make sure the custom import path is used and not a
  2773  // direct path to the underlying code hosting site.
  2774  //
  2775  // Import path checking is disabled for code found within vendor trees.
  2776  // This makes it possible to copy code into alternate locations in vendor trees
  2777  // without needing to update import comments.
  2778  //
  2779  // Import path checking is also disabled when using modules.
  2780  // Import path comments are obsoleted by the go.mod file's module statement.
  2781  //
  2782  // See https://golang.org/s/go14customimport for details.
  2783  //
  2784  // # Modules, module versions, and more
  2785  //
  2786  // Modules are how Go manages dependencies.
  2787  //
  2788  // A module is a collection of packages that are released, versioned, and
  2789  // distributed together. Modules may be downloaded directly from version control
  2790  // repositories or from module proxy servers.
  2791  //
  2792  // For a series of tutorials on modules, see
  2793  // https://golang.org/doc/tutorial/create-module.
  2794  //
  2795  // For a detailed reference on modules, see https://golang.org/ref/mod.
  2796  //
  2797  // By default, the go command may download modules from https://proxy.golang.org.
  2798  // It may authenticate modules using the checksum database at
  2799  // https://sum.golang.org. Both services are operated by the Go team at Google.
  2800  // The privacy policies for these services are available at
  2801  // https://proxy.golang.org/privacy and https://sum.golang.org/privacy,
  2802  // respectively.
  2803  //
  2804  // The go command's download behavior may be configured using GOPROXY, GOSUMDB,
  2805  // GOPRIVATE, and other environment variables. See 'go help environment'
  2806  // and https://golang.org/ref/mod#private-module-privacy for more information.
  2807  //
  2808  // # Module authentication using go.sum
  2809  //
  2810  // When the go command downloads a module zip file or go.mod file into the
  2811  // module cache, it computes a cryptographic hash and compares it with a known
  2812  // value to verify the file hasn't changed since it was first downloaded. Known
  2813  // hashes are stored in a file in the module root directory named go.sum. Hashes
  2814  // may also be downloaded from the checksum database depending on the values of
  2815  // GOSUMDB, GOPRIVATE, and GONOSUMDB.
  2816  //
  2817  // For details, see https://golang.org/ref/mod#authenticating.
  2818  //
  2819  // # Package lists and patterns
  2820  //
  2821  // Many commands apply to a set of packages:
  2822  //
  2823  //	go <action> [packages]
  2824  //
  2825  // Usually, [packages] is a list of import paths.
  2826  //
  2827  // An import path that is a rooted path or that begins with
  2828  // a . or .. element is interpreted as a file system path and
  2829  // denotes the package in that directory.
  2830  //
  2831  // Otherwise, the import path P denotes the package found in
  2832  // the directory DIR/src/P for some DIR listed in the GOPATH
  2833  // environment variable (For more details see: 'go help gopath').
  2834  //
  2835  // If no import paths are given, the action applies to the
  2836  // package in the current directory.
  2837  //
  2838  // There are four reserved names for paths that should not be used
  2839  // for packages to be built with the go tool:
  2840  //
  2841  // - "main" denotes the top-level package in a stand-alone executable.
  2842  //
  2843  // - "all" expands to all packages found in all the GOPATH
  2844  // trees. For example, 'go list all' lists all the packages on the local
  2845  // system. When using modules, "all" expands to all packages in
  2846  // the main module and their dependencies, including dependencies
  2847  // needed by tests of any of those.
  2848  //
  2849  // - "std" is like all but expands to just the packages in the standard
  2850  // Go library.
  2851  //
  2852  // - "cmd" expands to the Go repository's commands and their
  2853  // internal libraries.
  2854  //
  2855  // Import paths beginning with "cmd/" only match source code in
  2856  // the Go repository.
  2857  //
  2858  // An import path is a pattern if it includes one or more "..." wildcards,
  2859  // each of which can match any string, including the empty string and
  2860  // strings containing slashes. Such a pattern expands to all package
  2861  // directories found in the GOPATH trees with names matching the
  2862  // patterns.
  2863  //
  2864  // To make common patterns more convenient, there are two special cases.
  2865  // First, /... at the end of the pattern can match an empty string,
  2866  // so that net/... matches both net and packages in its subdirectories, like net/http.
  2867  // Second, any slash-separated pattern element containing a wildcard never
  2868  // participates in a match of the "vendor" element in the path of a vendored
  2869  // package, so that ./... does not match packages in subdirectories of
  2870  // ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do.
  2871  // Note, however, that a directory named vendor that itself contains code
  2872  // is not a vendored package: cmd/vendor would be a command named vendor,
  2873  // and the pattern cmd/... matches it.
  2874  // See golang.org/s/go15vendor for more about vendoring.
  2875  //
  2876  // An import path can also name a package to be downloaded from
  2877  // a remote repository. Run 'go help importpath' for details.
  2878  //
  2879  // Every package in a program must have a unique import path.
  2880  // By convention, this is arranged by starting each path with a
  2881  // unique prefix that belongs to you. For example, paths used
  2882  // internally at Google all begin with 'google', and paths
  2883  // denoting remote repositories begin with the path to the code,
  2884  // such as 'github.com/user/repo'.
  2885  //
  2886  // Packages in a program need not have unique package names,
  2887  // but there are two reserved package names with special meaning.
  2888  // The name main indicates a command, not a library.
  2889  // Commands are built into binaries and cannot be imported.
  2890  // The name documentation indicates documentation for
  2891  // a non-Go program in the directory. Files in package documentation
  2892  // are ignored by the go command.
  2893  //
  2894  // As a special case, if the package list is a list of .go files from a
  2895  // single directory, the command is applied to a single synthesized
  2896  // package made up of exactly those files, ignoring any build constraints
  2897  // in those files and ignoring any other files in the directory.
  2898  //
  2899  // Directory and file names that begin with "." or "_" are ignored
  2900  // by the go tool, as are directories named "testdata".
  2901  //
  2902  // # Configuration for downloading non-public code
  2903  //
  2904  // The go command defaults to downloading modules from the public Go module
  2905  // mirror at proxy.golang.org. It also defaults to validating downloaded modules,
  2906  // regardless of source, against the public Go checksum database at sum.golang.org.
  2907  // These defaults work well for publicly available source code.
  2908  //
  2909  // The GOPRIVATE environment variable controls which modules the go command
  2910  // considers to be private (not available publicly) and should therefore not use
  2911  // the proxy or checksum database. The variable is a comma-separated list of
  2912  // glob patterns (in the syntax of Go's path.Match) of module path prefixes.
  2913  // For example,
  2914  //
  2915  //	GOPRIVATE=*.corp.example.com,rsc.io/private
  2916  //
  2917  // causes the go command to treat as private any module with a path prefix
  2918  // matching either pattern, including git.corp.example.com/xyzzy, rsc.io/private,
  2919  // and rsc.io/private/quux.
  2920  //
  2921  // For fine-grained control over module download and validation, the GONOPROXY
  2922  // and GONOSUMDB environment variables accept the same kind of glob list
  2923  // and override GOPRIVATE for the specific decision of whether to use the proxy
  2924  // and checksum database, respectively.
  2925  //
  2926  // For example, if a company ran a module proxy serving private modules,
  2927  // users would configure go using:
  2928  //
  2929  //	GOPRIVATE=*.corp.example.com
  2930  //	GOPROXY=proxy.example.com
  2931  //	GONOPROXY=none
  2932  //
  2933  // The GOPRIVATE variable is also used to define the "public" and "private"
  2934  // patterns for the GOVCS variable; see 'go help vcs'. For that usage,
  2935  // GOPRIVATE applies even in GOPATH mode. In that case, it matches import paths
  2936  // instead of module paths.
  2937  //
  2938  // The 'go env -w' command (see 'go help env') can be used to set these variables
  2939  // for future go command invocations.
  2940  //
  2941  // For more details, see https://golang.org/ref/mod#private-modules.
  2942  //
  2943  // # Testing flags
  2944  //
  2945  // The 'go test' command takes both flags that apply to 'go test' itself
  2946  // and flags that apply to the resulting test binary.
  2947  //
  2948  // Several of the flags control profiling and write an execution profile
  2949  // suitable for "go tool pprof"; run "go tool pprof -h" for more
  2950  // information. The --alloc_space, --alloc_objects, and --show_bytes
  2951  // options of pprof control how the information is presented.
  2952  //
  2953  // The following flags are recognized by the 'go test' command and
  2954  // control the execution of any test:
  2955  //
  2956  //	-bench regexp
  2957  //	    Run only those benchmarks matching a regular expression.
  2958  //	    By default, no benchmarks are run.
  2959  //	    To run all benchmarks, use '-bench .' or '-bench=.'.
  2960  //	    The regular expression is split by unbracketed slash (/)
  2961  //	    characters into a sequence of regular expressions, and each
  2962  //	    part of a benchmark's identifier must match the corresponding
  2963  //	    element in the sequence, if any. Possible parents of matches
  2964  //	    are run with b.N=1 to identify sub-benchmarks. For example,
  2965  //	    given -bench=X/Y, top-level benchmarks matching X are run
  2966  //	    with b.N=1 to find any sub-benchmarks matching Y, which are
  2967  //	    then run in full.
  2968  //
  2969  //	-benchtime t
  2970  //	    Run enough iterations of each benchmark to take t, specified
  2971  //	    as a time.Duration (for example, -benchtime 1h30s).
  2972  //	    The default is 1 second (1s).
  2973  //	    The special syntax Nx means to run the benchmark N times
  2974  //	    (for example, -benchtime 100x).
  2975  //
  2976  //	-count n
  2977  //	    Run each test, benchmark, and fuzz seed n times (default 1).
  2978  //	    If -cpu is set, run n times for each GOMAXPROCS value.
  2979  //	    Examples are always run once. -count does not apply to
  2980  //	    fuzz tests matched by -fuzz.
  2981  //
  2982  //	-cover
  2983  //	    Enable coverage analysis.
  2984  //	    Note that because coverage works by annotating the source
  2985  //	    code before compilation, compilation and test failures with
  2986  //	    coverage enabled may report line numbers that don't correspond
  2987  //	    to the original sources.
  2988  //
  2989  //	-covermode set,count,atomic
  2990  //	    Set the mode for coverage analysis for the package[s]
  2991  //	    being tested. The default is "set" unless -race is enabled,
  2992  //	    in which case it is "atomic".
  2993  //	    The values:
  2994  //		set: bool: does this statement run?
  2995  //		count: int: how many times does this statement run?
  2996  //		atomic: int: count, but correct in multithreaded tests;
  2997  //			significantly more expensive.
  2998  //	    Sets -cover.
  2999  //
  3000  //	-coverpkg pattern1,pattern2,pattern3
  3001  //	    Apply coverage analysis in each test to packages matching the patterns.
  3002  //	    The default is for each test to analyze only the package being tested.
  3003  //	    See 'go help packages' for a description of package patterns.
  3004  //	    Sets -cover.
  3005  //
  3006  //	-cpu 1,2,4
  3007  //	    Specify a list of GOMAXPROCS values for which the tests, benchmarks or
  3008  //	    fuzz tests should be executed. The default is the current value
  3009  //	    of GOMAXPROCS. -cpu does not apply to fuzz tests matched by -fuzz.
  3010  //
  3011  //	-failfast
  3012  //	    Do not start new tests after the first test failure.
  3013  //
  3014  //	-fullpath
  3015  //	    Show full file names in the error messages.
  3016  //
  3017  //	-fuzz regexp
  3018  //	    Run the fuzz test matching the regular expression. When specified,
  3019  //	    the command line argument must match exactly one package within the
  3020  //	    main module, and regexp must match exactly one fuzz test within
  3021  //	    that package. Fuzzing will occur after tests, benchmarks, seed corpora
  3022  //	    of other fuzz tests, and examples have completed. See the Fuzzing
  3023  //	    section of the testing package documentation for details.
  3024  //
  3025  //	-fuzztime t
  3026  //	    Run enough iterations of the fuzz target during fuzzing to take t,
  3027  //	    specified as a time.Duration (for example, -fuzztime 1h30s).
  3028  //		The default is to run forever.
  3029  //	    The special syntax Nx means to run the fuzz target N times
  3030  //	    (for example, -fuzztime 1000x).
  3031  //
  3032  //	-fuzzminimizetime t
  3033  //	    Run enough iterations of the fuzz target during each minimization
  3034  //	    attempt to take t, as specified as a time.Duration (for example,
  3035  //	    -fuzzminimizetime 30s).
  3036  //		The default is 60s.
  3037  //	    The special syntax Nx means to run the fuzz target N times
  3038  //	    (for example, -fuzzminimizetime 100x).
  3039  //
  3040  //	-json
  3041  //	    Log verbose output and test results in JSON. This presents the
  3042  //	    same information as the -v flag in a machine-readable format.
  3043  //
  3044  //	-list regexp
  3045  //	    List tests, benchmarks, fuzz tests, or examples matching the regular
  3046  //	    expression. No tests, benchmarks, fuzz tests, or examples will be run.
  3047  //	    This will only list top-level tests. No subtest or subbenchmarks will be
  3048  //	    shown.
  3049  //
  3050  //	-parallel n
  3051  //	    Allow parallel execution of test functions that call t.Parallel, and
  3052  //	    fuzz targets that call t.Parallel when running the seed corpus.
  3053  //	    The value of this flag is the maximum number of tests to run
  3054  //	    simultaneously.
  3055  //	    While fuzzing, the value of this flag is the maximum number of
  3056  //	    subprocesses that may call the fuzz function simultaneously, regardless of
  3057  //	    whether T.Parallel is called.
  3058  //	    By default, -parallel is set to the value of GOMAXPROCS.
  3059  //	    Setting -parallel to values higher than GOMAXPROCS may cause degraded
  3060  //	    performance due to CPU contention, especially when fuzzing.
  3061  //	    Note that -parallel only applies within a single test binary.
  3062  //	    The 'go test' command may run tests for different packages
  3063  //	    in parallel as well, according to the setting of the -p flag
  3064  //	    (see 'go help build').
  3065  //
  3066  //	-run regexp
  3067  //	    Run only those tests, examples, and fuzz tests matching the regular
  3068  //	    expression. For tests, the regular expression is split by unbracketed
  3069  //	    slash (/) characters into a sequence of regular expressions, and each
  3070  //	    part of a test's identifier must match the corresponding element in
  3071  //	    the sequence, if any. Note that possible parents of matches are
  3072  //	    run too, so that -run=X/Y matches and runs and reports the result
  3073  //	    of all tests matching X, even those without sub-tests matching Y,
  3074  //	    because it must run them to look for those sub-tests.
  3075  //	    See also -skip.
  3076  //
  3077  //	-short
  3078  //	    Tell long-running tests to shorten their run time.
  3079  //	    It is off by default but set during all.bash so that installing
  3080  //	    the Go tree can run a sanity check but not spend time running
  3081  //	    exhaustive tests.
  3082  //
  3083  //	-shuffle off,on,N
  3084  //	    Randomize the execution order of tests and benchmarks.
  3085  //	    It is off by default. If -shuffle is set to on, then it will seed
  3086  //	    the randomizer using the system clock. If -shuffle is set to an
  3087  //	    integer N, then N will be used as the seed value. In both cases,
  3088  //	    the seed will be reported for reproducibility.
  3089  //
  3090  //	-skip regexp
  3091  //	    Run only those tests, examples, fuzz tests, and benchmarks that
  3092  //	    do not match the regular expression. Like for -run and -bench,
  3093  //	    for tests and benchmarks, the regular expression is split by unbracketed
  3094  //	    slash (/) characters into a sequence of regular expressions, and each
  3095  //	    part of a test's identifier must match the corresponding element in
  3096  //	    the sequence, if any.
  3097  //
  3098  //	-timeout d
  3099  //	    If a test binary runs longer than duration d, panic.
  3100  //	    If d is 0, the timeout is disabled.
  3101  //	    The default is 10 minutes (10m).
  3102  //
  3103  //	-v
  3104  //	    Verbose output: log all tests as they are run. Also print all
  3105  //	    text from Log and Logf calls even if the test succeeds.
  3106  //
  3107  //	-vet list
  3108  //	    Configure the invocation of "go vet" during "go test"
  3109  //	    to use the comma-separated list of vet checks.
  3110  //	    If list is empty, "go test" runs "go vet" with a curated list of
  3111  //	    checks believed to be always worth addressing.
  3112  //	    If list is "off", "go test" does not run "go vet" at all.
  3113  //
  3114  // The following flags are also recognized by 'go test' and can be used to
  3115  // profile the tests during execution:
  3116  //
  3117  //	-benchmem
  3118  //	    Print memory allocation statistics for benchmarks.
  3119  //	    Allocations made in C or using C.malloc are not counted.
  3120  //
  3121  //	-blockprofile block.out
  3122  //	    Write a goroutine blocking profile to the specified file
  3123  //	    when all tests are complete.
  3124  //	    Writes test binary as -c would.
  3125  //
  3126  //	-blockprofilerate n
  3127  //	    Control the detail provided in goroutine blocking profiles by
  3128  //	    calling runtime.SetBlockProfileRate with n.
  3129  //	    See 'go doc runtime.SetBlockProfileRate'.
  3130  //	    The profiler aims to sample, on average, one blocking event every
  3131  //	    n nanoseconds the program spends blocked. By default,
  3132  //	    if -test.blockprofile is set without this flag, all blocking events
  3133  //	    are recorded, equivalent to -test.blockprofilerate=1.
  3134  //
  3135  //	-coverprofile cover.out
  3136  //	    Write a coverage profile to the file after all tests have passed.
  3137  //	    Sets -cover.
  3138  //
  3139  //	-cpuprofile cpu.out
  3140  //	    Write a CPU profile to the specified file before exiting.
  3141  //	    Writes test binary as -c would.
  3142  //
  3143  //	-memprofile mem.out
  3144  //	    Write an allocation profile to the file after all tests have passed.
  3145  //	    Writes test binary as -c would.
  3146  //
  3147  //	-memprofilerate n
  3148  //	    Enable more precise (and expensive) memory allocation profiles by
  3149  //	    setting runtime.MemProfileRate. See 'go doc runtime.MemProfileRate'.
  3150  //	    To profile all memory allocations, use -test.memprofilerate=1.
  3151  //
  3152  //	-mutexprofile mutex.out
  3153  //	    Write a mutex contention profile to the specified file
  3154  //	    when all tests are complete.
  3155  //	    Writes test binary as -c would.
  3156  //
  3157  //	-mutexprofilefraction n
  3158  //	    Sample 1 in n stack traces of goroutines holding a
  3159  //	    contended mutex.
  3160  //
  3161  //	-outputdir directory
  3162  //	    Place output files from profiling in the specified directory,
  3163  //	    by default the directory in which "go test" is running.
  3164  //
  3165  //	-trace trace.out
  3166  //	    Write an execution trace to the specified file before exiting.
  3167  //
  3168  // Each of these flags is also recognized with an optional 'test.' prefix,
  3169  // as in -test.v. When invoking the generated test binary (the result of
  3170  // 'go test -c') directly, however, the prefix is mandatory.
  3171  //
  3172  // The 'go test' command rewrites or removes recognized flags,
  3173  // as appropriate, both before and after the optional package list,
  3174  // before invoking the test binary.
  3175  //
  3176  // For instance, the command
  3177  //
  3178  //	go test -v -myflag testdata -cpuprofile=prof.out -x
  3179  //
  3180  // will compile the test binary and then run it as
  3181  //
  3182  //	pkg.test -test.v -myflag testdata -test.cpuprofile=prof.out
  3183  //
  3184  // (The -x flag is removed because it applies only to the go command's
  3185  // execution, not to the test itself.)
  3186  //
  3187  // The test flags that generate profiles (other than for coverage) also
  3188  // leave the test binary in pkg.test for use when analyzing the profiles.
  3189  //
  3190  // When 'go test' runs a test binary, it does so from within the
  3191  // corresponding package's source code directory. Depending on the test,
  3192  // it may be necessary to do the same when invoking a generated test
  3193  // binary directly. Because that directory may be located within the
  3194  // module cache, which may be read-only and is verified by checksums, the
  3195  // test must not write to it or any other directory within the module
  3196  // unless explicitly requested by the user (such as with the -fuzz flag,
  3197  // which writes failures to testdata/fuzz).
  3198  //
  3199  // The command-line package list, if present, must appear before any
  3200  // flag not known to the go test command. Continuing the example above,
  3201  // the package list would have to appear before -myflag, but could appear
  3202  // on either side of -v.
  3203  //
  3204  // When 'go test' runs in package list mode, 'go test' caches successful
  3205  // package test results to avoid unnecessary repeated running of tests. To
  3206  // disable test caching, use any test flag or argument other than the
  3207  // cacheable flags. The idiomatic way to disable test caching explicitly
  3208  // is to use -count=1.
  3209  //
  3210  // To keep an argument for a test binary from being interpreted as a
  3211  // known flag or a package name, use -args (see 'go help test') which
  3212  // passes the remainder of the command line through to the test binary
  3213  // uninterpreted and unaltered.
  3214  //
  3215  // For instance, the command
  3216  //
  3217  //	go test -v -args -x -v
  3218  //
  3219  // will compile the test binary and then run it as
  3220  //
  3221  //	pkg.test -test.v -x -v
  3222  //
  3223  // Similarly,
  3224  //
  3225  //	go test -args math
  3226  //
  3227  // will compile the test binary and then run it as
  3228  //
  3229  //	pkg.test math
  3230  //
  3231  // In the first example, the -x and the second -v are passed through to the
  3232  // test binary unchanged and with no effect on the go command itself.
  3233  // In the second example, the argument math is passed through to the test
  3234  // binary, instead of being interpreted as the package list.
  3235  //
  3236  // # Testing functions
  3237  //
  3238  // The 'go test' command expects to find test, benchmark, and example functions
  3239  // in the "*_test.go" files corresponding to the package under test.
  3240  //
  3241  // A test function is one named TestXxx (where Xxx does not start with a
  3242  // lower case letter) and should have the signature,
  3243  //
  3244  //	func TestXxx(t *testing.T) { ... }
  3245  //
  3246  // A benchmark function is one named BenchmarkXxx and should have the signature,
  3247  //
  3248  //	func BenchmarkXxx(b *testing.B) { ... }
  3249  //
  3250  // A fuzz test is one named FuzzXxx and should have the signature,
  3251  //
  3252  //	func FuzzXxx(f *testing.F) { ... }
  3253  //
  3254  // An example function is similar to a test function but, instead of using
  3255  // *testing.T to report success or failure, prints output to os.Stdout.
  3256  // If the last comment in the function starts with "Output:" then the output
  3257  // is compared exactly against the comment (see examples below). If the last
  3258  // comment begins with "Unordered output:" then the output is compared to the
  3259  // comment, however the order of the lines is ignored. An example with no such
  3260  // comment is compiled but not executed. An example with no text after
  3261  // "Output:" is compiled, executed, and expected to produce no output.
  3262  //
  3263  // Godoc displays the body of ExampleXxx to demonstrate the use
  3264  // of the function, constant, or variable Xxx. An example of a method M with
  3265  // receiver type T or *T is named ExampleT_M. There may be multiple examples
  3266  // for a given function, constant, or variable, distinguished by a trailing _xxx,
  3267  // where xxx is a suffix not beginning with an upper case letter.
  3268  //
  3269  // Here is an example of an example:
  3270  //
  3271  //	func ExamplePrintln() {
  3272  //		Println("The output of\nthis example.")
  3273  //		// Output: The output of
  3274  //		// this example.
  3275  //	}
  3276  //
  3277  // Here is another example where the ordering of the output is ignored:
  3278  //
  3279  //	func ExamplePerm() {
  3280  //		for _, value := range Perm(4) {
  3281  //			fmt.Println(value)
  3282  //		}
  3283  //
  3284  //		// Unordered output: 4
  3285  //		// 2
  3286  //		// 1
  3287  //		// 3
  3288  //		// 0
  3289  //	}
  3290  //
  3291  // The entire test file is presented as the example when it contains a single
  3292  // example function, at least one other function, type, variable, or constant
  3293  // declaration, and no tests, benchmarks, or fuzz tests.
  3294  //
  3295  // See the documentation of the testing package for more information.
  3296  //
  3297  // # Controlling version control with GOVCS
  3298  //
  3299  // The 'go get' command can run version control commands like git
  3300  // to download imported code. This functionality is critical to the decentralized
  3301  // Go package ecosystem, in which code can be imported from any server,
  3302  // but it is also a potential security problem, if a malicious server finds a
  3303  // way to cause the invoked version control command to run unintended code.
  3304  //
  3305  // To balance the functionality and security concerns, the 'go get' command
  3306  // by default will only use git and hg to download code from public servers.
  3307  // But it will use any known version control system (bzr, fossil, git, hg, svn)
  3308  // to download code from private servers, defined as those hosting packages
  3309  // matching the GOPRIVATE variable (see 'go help private'). The rationale behind
  3310  // allowing only Git and Mercurial is that these two systems have had the most
  3311  // attention to issues of being run as clients of untrusted servers. In contrast,
  3312  // Bazaar, Fossil, and Subversion have primarily been used in trusted,
  3313  // authenticated environments and are not as well scrutinized as attack surfaces.
  3314  //
  3315  // The version control command restrictions only apply when using direct version
  3316  // control access to download code. When downloading modules from a proxy,
  3317  // 'go get' uses the proxy protocol instead, which is always permitted.
  3318  // By default, the 'go get' command uses the Go module mirror (proxy.golang.org)
  3319  // for public packages and only falls back to version control for private
  3320  // packages or when the mirror refuses to serve a public package (typically for
  3321  // legal reasons). Therefore, clients can still access public code served from
  3322  // Bazaar, Fossil, or Subversion repositories by default, because those downloads
  3323  // use the Go module mirror, which takes on the security risk of running the
  3324  // version control commands using a custom sandbox.
  3325  //
  3326  // The GOVCS variable can be used to change the allowed version control systems
  3327  // for specific packages (identified by a module or import path).
  3328  // The GOVCS variable applies when building package in both module-aware mode
  3329  // and GOPATH mode. When using modules, the patterns match against the module path.
  3330  // When using GOPATH, the patterns match against the import path corresponding to
  3331  // the root of the version control repository.
  3332  //
  3333  // The general form of the GOVCS setting is a comma-separated list of
  3334  // pattern:vcslist rules. The pattern is a glob pattern that must match
  3335  // one or more leading elements of the module or import path. The vcslist
  3336  // is a pipe-separated list of allowed version control commands, or "all"
  3337  // to allow use of any known command, or "off" to disallow all commands.
  3338  // Note that if a module matches a pattern with vcslist "off", it may still be
  3339  // downloaded if the origin server uses the "mod" scheme, which instructs the
  3340  // go command to download the module using the GOPROXY protocol.
  3341  // The earliest matching pattern in the list applies, even if later patterns
  3342  // might also match.
  3343  //
  3344  // For example, consider:
  3345  //
  3346  //	GOVCS=github.com:git,evil.com:off,*:git|hg
  3347  //
  3348  // With this setting, code with a module or import path beginning with
  3349  // github.com/ can only use git; paths on evil.com cannot use any version
  3350  // control command, and all other paths (* matches everything) can use
  3351  // only git or hg.
  3352  //
  3353  // The special patterns "public" and "private" match public and private
  3354  // module or import paths. A path is private if it matches the GOPRIVATE
  3355  // variable; otherwise it is public.
  3356  //
  3357  // If no rules in the GOVCS variable match a particular module or import path,
  3358  // the 'go get' command applies its default rule, which can now be summarized
  3359  // in GOVCS notation as 'public:git|hg,private:all'.
  3360  //
  3361  // To allow unfettered use of any version control system for any package, use:
  3362  //
  3363  //	GOVCS=*:all
  3364  //
  3365  // To disable all use of version control, use:
  3366  //
  3367  //	GOVCS=*:off
  3368  //
  3369  // The 'go env -w' command (see 'go help env') can be used to set the GOVCS
  3370  // variable for future go command invocations.
  3371  package main
  3372  

View as plain text