Adding upstream version 2:1.19~1.upstream/2%1.19_1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 353 insertions, 0 deletions

diff --git a/man/go-list.1 b/man/go-list.1
new file mode 100644
index 0000000..12849b4
--- /dev/null
+++ b/man/go-list.1
@@ -0,0 +1,353 @@
+.\"                                      Hey, EMACS: -*- nroff -*-
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.TH GO-LIST 1 "2022-08-02"
+.\" Please adjust this date whenever revising the manpage.
+.SH NAME
+go-list \- list packages or modules
+.SH SYNOPSIS
+.B go list
+.RB [ \-f
+.IR format ]
+.RB [ \-json ]
+.RB [ \-m ]
+.RI [ "list flags" ]
+.RI [ "build flags" ]
+.RI [ packages ]
+.SH DESCRIPTION
+List lists the packages named by the import paths, one per line.
+.br
+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.
+.P
+The default output shows the package import path:
+
+.Vb 6
+\&      bytes
+\&      encoding/json
+\&      github.com/gorilla/mux
+\&      golang.org/x/net/html
+.Ve
+.SH OPTIONS
+.TP
+.B \-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:
+
+.Vb 6
+\&    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
+\&    }
+.Ve
+
+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
+
+.Vb 6
+\&    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
+\&    }
+.Ve
+
+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:
+
+.Vb 6
+\&    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
+\&    }
+.Ve
+
+For more information about the meaning of these fields see the documentation
+for the go/build package's Context type.
+.TP
+.B \-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.
+.TP
+.B \-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.
+.TP
+.B \-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.
+.TP
+.B \-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).
+.TP
+.B \-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.
+.TP
+.B \-find
+The \-find flag causes list to identify the named packages but not
+resolve their dependencies: the Imports and Deps lists will be empty.
+.TP
+.B \-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).
+.P
+The Dir, Target, Shlib, Root, ConflictDir, and Export file paths
+are all absolute paths.
+.P
+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".
+.TP
+.B \-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:
+
+.Vb 6
+\&    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
+\&    }
+.Ve
+
+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:
+
+.Vb 6
+\&    my/main/module
+\&    golang.org/x/text v0.3.0 => /tmp/text
+\&    rsc.io/pdf v0.1.1
+.Ve
+
+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.)
+.TP
+.B \-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:
+
+.Vb 6
+\&    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]
+.Ve
+
+(For tools, 'go list \-m \-u \-json all' may be more convenient to parse.)
+.TP
+.B \-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.
+.TP
+.B \-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.
+.P
+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.
+.P
+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.
+.P
+When using \-m, the \-reuse=old.json flag accepts the name of file containing
+the JSON output of a previous \(oqgo list \-m \-json\(cq 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.
+.P
+For more about build flags, see \fBgo-build\fP(1) or 'go help build'.
+.P
+For more about specifying packages, see \fBgo-packages\fP(7) or 'go help packages'.
+.P
+For more about modules, see https://golang.org/ref/mod.
+.SH 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).