What does `go list` do in Go's toolset?

Question

go list has some inconsistent behavior that I am having a difficult time understanding. When I enter the go help list command, it says:

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

List lists the named packages, one per line.

This does not make much sense to me. Which "named packages" does it list? I see at the end of the command, that there's a [packages] argument. Does it list packages mentioned there? This is not clear to me. Several times, I've run go list in a go project working directory that has a go.mod and even vendor directory, and all I get is a single output for the current project. The help page also states:

The default output shows the package import path:

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

I have no idea what it's talking about here. To me, this is literally a list of 4 completely separate software projects one-after-the-other with no apparent relation.

Please share a better description of what this tool does, specifically which "named packages" it lists, and perhaps some common use-cases and examples of this, as well as any potential side-effects.

Answer 1

Which "named packages" does it list? I see at the end of the command, that there's a [packages] argument. Does it list packages mentioned there?

Yes, the packages are named by the packages argument to the command. Run go help packages for information on specifying packages.

Several times, I've run go list in a go project working directory that has a go.mod and even vendor directory, and all I get is a single output for the current project

The packages argument defaults to the package in the current working directory. The command go list prints the import path of the package in the current working directory.

The default output shows the package import … this is literally a list of 4 completely separate software projects one-after-the-other with no apparent relation.

This part of documentation shows the default output format for some example packages. Use the [-f format] or [-json] to specify other output formats.

The example output in the documentation is produced by the the command go list bytes encoding/json github.com/gorilla/mux golang.org/x/net/html .

Some uses cases:

go list all : print import path of the main module and all dependencies.

go list -f {{.Dir}} github.com/gorilla/mux : print the directory for the package github.com/gorilla/mux.