Provided by: golang-go_1.21~2_amd64 bug

NAME

       go-list - list packages or modules

SYNOPSIS

       go list [-f format] [-json] [-m] [list flags] [build flags] [packages]

DESCRIPTION

       List lists the packages named by the import paths, one per line.
       The  most  commonly-used  flags  are  -f  and  -json, which control the form of the output
       printed for each package. Other  list  flags,  documented  below,  control  more  specific
       details.

       The default output shows the package import path:

             bytes
             encoding/json
             github.com/gorilla/mux
             golang.org/x/net/html

OPTIONS

       -f     The -f flag specifies an alternate format for the list, using the syntax of package
              template.  The default output is equivalent to -f  '{{.ImportPath}}'.   The  struct
              being passed to the template is:

                  type Package struct {
                      Dir           string   // directory containing package sources
                      ImportPath    string   // import path of package in dir
                      ImportComment string   // path in import comment on package statement
                      Name          string   // package name
                      Doc           string   // package documentation string
                      Target        string   // install path
                      Shlib         string   // the shared library that contains this package (only set when -linkshared)
                      Goroot        bool     // is this package in the Go root?
                      Standard      bool     // is this package part of the standard Go library?
                      Stale         bool     // would 'go install' do anything for this package?
                      StaleReason   string   // explanation for Stale==true
                      Root          string   // Go root or Go path dir containing this package
                      ConflictDir   string   // this directory shadows Dir in $GOPATH
                      BinaryOnly    bool     // binary-only package (no longer supported)
                      ForTest       string   // package is only for use in named test
                      Export        string   // file containing export data (when using -export)
                      BuildID       string   // build ID of the compiled package (when using -export)
                      Module        *Module  // info about package's containing module, if any (can be nil)
                      Match         []string // command-line patterns matching this package
                      DepOnly       bool     // package is only a dependency, not explicitly listed

                      // Source files
                      GoFiles         []string   // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)
                      CgoFiles        []string   // .go source files that import "C"
                      CompiledGoFiles []string   // .go files presented to compiler (when using -compiled)
                      IgnoredGoFiles  []string   // .go source files ignored due to build constraints
                      IgnoredOtherFiles []string // non-.go source files ignored due to build constraints
                      CFiles          []string   // .c source files
                      CXXFiles        []string   // .cc, .cxx and .cpp source files
                      MFiles          []string   // .m source files
                      HFiles          []string   // .h, .hh, .hpp and .hxx source files
                      FFiles          []string   // .f, .F, .for and .f90 Fortran source files
                      SFiles          []string   // .s source files
                      SwigFiles       []string   // .swig files
                      SwigCXXFiles    []string   // .swigcxx files
                      SysoFiles       []string   // .syso object files to add to archive
                      TestGoFiles     []string   // _test.go files in package
                      XTestGoFiles    []string   // _test.go files outside package

                      // Embedded files
                      EmbedPatterns      []string // //go:embed patterns
                      EmbedFiles         []string // files matched by EmbedPatterns
                      TestEmbedPatterns  []string // //go:embed patterns in TestGoFiles
                      TestEmbedFiles     []string // files matched by TestEmbedPatterns
                      XTestEmbedPatterns []string // //go:embed patterns in XTestGoFiles
                      XTestEmbedFiles    []string // files matched by XTestEmbedPatterns

                      // Cgo directives
                      CgoCFLAGS    []string // cgo: flags for C compiler
                      CgoCPPFLAGS  []string // cgo: flags for C preprocessor
                      CgoCXXFLAGS  []string // cgo: flags for C++ compiler
                      CgoFFLAGS    []string // cgo: flags for Fortran compiler
                      CgoLDFLAGS   []string // cgo: flags for linker
                      CgoPkgConfig []string // cgo: pkg-config names

                      // Dependency information
                      Imports      []string          // import paths used by this package
                      ImportMap    map[string]string // map from source import to ImportPath (identity entries omitted)
                      Deps         []string          // all (recursively) imported dependencies
                      TestImports  []string          // imports from TestGoFiles
                      XTestImports []string          // imports from XTestGoFiles

                      // Error information
                      Incomplete bool            // this package or a dependency has an error
                      Error      *PackageError   // error loading package
                      DepsErrors []*PackageError // errors loading dependencies
                  }

              Packages  stored  in vendor directories report an ImportPath that includes the path
              to the vendor directory (for example, "d/vendor/p" instead of  "p"),  so  that  the
              ImportPath  uniquely  identifies  a  given  copy  of a package.  The Imports, Deps,
              TestImports, and XTestImports lists also contain these expanded import  paths.  See
              golang.org/s/go15vendor for more about vendoring.

              The error information, if any, is

                  type PackageError struct {
                      ImportStack   []string // shortest path from package named on command line to this one
                      Pos           string   // position of error (if present, file:line:col)
                      Err           string   // the error itself
                  }

              The  module  information  is  a Module struct, defined in the discussion of list -m
              below.

              The template function "join" calls strings.Join.

              The template function "context" returns the build context, defined as:

                  type Context struct {
                      GOARCH        string   // target architecture
                      GOOS          string   // target operating system
                      GOROOT        string   // Go root
                      GOPATH        string   // Go path
                      CgoEnabled    bool     // whether cgo can be used
                      UseAllFiles   bool     // use files regardless of +build lines, file names
                      Compiler      string   // compiler to assume when computing target paths
                      BuildTags     []string // build constraints to match in +build lines
                      ToolTags      []string // toolchain-specific build constraints
                      ReleaseTags   []string // releases the current release is compatible with
                      InstallSuffix string   // suffix to use in the name of the install dir
                  }

              For more information about the meaning of these fields see  the  documentation  for
              the go/build package's Context type.

       -json  The  -json  flag  causes  the  package data to be printed in JSON format instead of
              using the template format. The JSON flag can optionally be provided with a  set  of
              comma-separated  required  field  names to be output.  If so, those required fields
              will always appear in JSON output, but others  may  be  omitted  to  save  work  in
              computing the JSON struct.

       -compiled
              The  -compiled  flag  causes  list  to  set  CompiledGoFiles to the Go source files
              presented to the compiler. Typically this means that it repeats the files listed in
              GoFiles  and  then  also  adds  the  Go  code  generated by processing CgoFiles and
              SwigFiles. The Imports list contains the union of all imports from both GoFiles and
              CompiledGoFiles.

       -deps  The -deps flag causes list to iterate over not just the named packages but also all
              their dependencies. It visits them in a depth-first post-order traversal, so that a
              package  is listed only after all its dependencies.  Packages not explicitly listed
              on the command line will have the DepOnly field set to true.

       -e     The -e flag changes the handling of erroneous packages, those that cannot be  found
              or  are  malformed.  By default, the list command prints an error to standard error
              for each erroneous package and omits the packages  from  consideration  during  the
              usual printing.  With the -e flag, the list command never prints errors to standard
              error and instead  processes  the  erroneous  packages  with  the  usual  printing.
              Erroneous  packages  will  have  a  non-empty ImportPath and a non-nil Error field;
              other information may or may not be missing (zeroed).

       -export
              The -export flag causes list to set  the  Export  field  to  the  name  of  a  file
              containing  up-to-date  export  information  for the given package, and the BuildID
              field to the build ID of the compiled package.

       -find  The -find flag causes list to identify the named packages  but  not  resolve  their
              dependencies: the Imports and Deps lists will be empty.

       -test  The  -test  flag  causes  list to report not only the named packages but also their
              test binaries (for packages with tests), to convey to source  code  analysis  tools
              exactly  how  test  binaries  are constructed.  The reported import path for a test
              binary is the import path of the package  followed  by  a  ".test"  suffix,  as  in
              "math/rand.test".   When  building  a  test,  it  is sometimes necessary to rebuild
              certain dependencies specially for that test  (most  commonly  the  tested  package
              itself).  The  reported  import  path of a package recompiled for a particular test
              binary is followed by a space and the name of the test binary in  brackets,  as  in
              "math/rand [math/rand.test]" or "regexp [sort.test]". The ForTest field is also set
              to the name of the package being tested ("math/rand"  or  "sort"  in  the  previous
              examples).

       The Dir, Target, Shlib, Root, ConflictDir, and Export file paths are all absolute paths.

       By  default,  the  lists GoFiles, CgoFiles, and so on hold names of files in Dir (that is,
       paths relative to Dir, not absolute paths).  The generated  files  added  when  using  the
       -compiled  and  -test  flags are absolute paths referring to cached copies of generated Go
       source files.  Although they are Go source files, the paths may not end in ".go".

       -m     The -m flag causes list to list modules instead of packages.

              When listing modules, the -f flag still specifies a format template applied to a Go
              struct, but now a Module struct:

                  type Module struct {
                      Path       string        // module path
                      Query      string        // version query corresponding to this version
                      Version    string        // module version
                      Versions   []string      // available module versions
                      Replace    *Module       // replaced by this module
                      Time       *time.Time    // time version was created
                      Update     *Module       // available update (with -u)
                      Main       bool          // is this the main module?
                      Indirect   bool          // module is only indirectly needed by main module
                      Dir        string        // directory holding local copy of files, if any
                      GoMod      string        // path to go.mod file describing module, if any
                      GoVersion  string        // go version used in module
                      Retracted  []string      // retraction information, if any (with -retracted or -u)
                      Deprecated string        // deprecation message, if any (with -u)
                      Error      *ModuleError  // error loading module
                      Origin     any           // provenance of module
                      Reuse      bool          // reuse of old module info is safe
                  }

                  type ModuleError struct {
                      Err string // the error itself
                  }

              The  file  GoMod  refers to may be outside the module directory if the module is in
              the module cache or if the -modfile flag is used.

              The default output is to print the module  path  and  then  information  about  the
              version and replacement if any.  For example, 'go list -m all' might print:

                  my/main/module
                  golang.org/x/text v0.3.0 => /tmp/text
                  rsc.io/pdf v0.1.1

              The Module struct has a String method that formats this line of output, so that the
              default format is equivalent to -f '{{.String}}'.

              Note that when a  module  has  been  replaced,  its  Replace  field  describes  the
              replacement  module,  and its Dir field is set to the replacement's source code, if
              present. (That is, if Replace is non-nil, then Dir is set to Replace.Dir,  with  no
              access to the replaced source code.)

       -u     The  -u flag adds information about available upgrades.  When the latest version of
              a given module is newer than the current one, list  -u  sets  the  Module's  Update
              field  to  information  about  the newer module. list -u will also set the module's
              Retracted field if the current version is retracted.  The  Module's  String  method
              indicates  an  available  upgrade by formatting the newer version in brackets after
              the current version.  If a version is  retracted,  the  string  "(retracted)"  will
              follow it.  For example, 'go list -m -u all' might print:

                  my/main/module
                  golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text
                  rsc.io/pdf v0.1.1 (retracted) [v0.1.2]

              (For tools, 'go list -m -u -json all' may be more convenient to parse.)

       -versions
              The  -versions flag causes list to set the Module's Versions field to a list of all
              known versions of that module, ordered according to semantic  versioning,  earliest
              to  latest.  The  flag also changes the default output format to display the module
              path followed by the space-separated version list.

       -retracted
              The -retracted flag causes  list  to  report  information  about  retracted  module
              versions. When -retracted is used with -f or -json, the Retracted field will be set
              to a string explaining why the version was retracted.  The  string  is  taken  from
              comments  on  the retract directive in the module's go.mod file. When -retracted is
              used with -versions,  retracted  versions  are  listed  together  with  unretracted
              versions. The -retracted flag may be used with or without -m.

       The  arguments  to  list  -m are interpreted as a list of modules, not packages.  The main
       module is the module containing the current directory.  The active modules  are  the  main
       module  and  its  dependencies.   With  no arguments, list -m shows the main module.  With
       arguments, list -m shows the modules specified  by  the  arguments.   Any  of  the  active
       modules  can be specified by its module path.  The special pattern "all" specifies all the
       active modules, first the main module and then dependencies  sorted  by  module  path.   A
       pattern  containing  "..."  specifies  the  active  modules  whose  module paths match the
       pattern.  A query of the form path@version specifies the result of that  query,  which  is
       not limited to active modules.  See 'go help modules' for more about module queries.

       The  template  function "module" takes a single string argument that must be a module path
       or query and returns the specified module as a Module struct.  If  an  error  occurs,  the
       result will be a Module struct with a non-nil Error field.

       When  using  -m,  the  -reuse=old.json  flag  accepts the name of file containing the JSON
       output of a previous ‘go list -m -json’ invocation with the same  set  of  modifier  flags
       (such  as  -u,  -retracted, and -versions).  The go command may use this file to determine
       that a  module  is  unchanged  since  the  previous  invocation  and  avoid  redownloading
       information  about it.  Modules that are not redownloaded will be marked in the new output
       by setting the Reuse field to true. Normally the module cache provides this kind of  reuse
       automatically;  the  -reuse  flag can be useful on systems that do not preserve the module
       cache.

       For more about build flags, see go-build(1) or 'go help build'.

       For more about specifying packages, see go-packages(7) or 'go help packages'.

       For more about modules, see https://golang.org/ref/mod.

AUTHOR

       This manual  page  was  written  by  Michael  Stapelberg  <stapelberg@debian.org>  and  is
       maintained  by  the Debian Go Compiler Team <team+go-compiler@tracker.debian.org> based on
       the output of 'go help list' for the Debian project (and may be used by others).

                                            2022-08-02                                 GO-LIST(1)