Go Reference ยท The go Command and Tools
The go list command
Reference for go list: print packages and modules, choose fields with -f templates, JSON output, -deps, -m, -u, -test and patterns like ./... and std.
go list prints information about packages (or, with -m, modules). By default it prints one import path per line, which makes it the standard way to expand a pattern such as ./... into a list of packages for scripts. With -f you pick exactly the fields you want using a Go template, and with -json you get everything as JSON.
Behind many other tools is the same data: which files belong to a package, what it imports, which build tags select it, and which module owns it. If you ever need to answer "what does this build actually include?", go list is the first tool to try.
go list ./... # all packages in this module go list -f '{{.ImportPath}}: {{.Imports}}' . go list -m all # every module in the build go list -deps -f '{{if not .Standard}}{{.ImportPath}}{{end}}' .
Try it
The data go list prints comes from the go/build package, and -f uses text/template. The examples use both: first to read a real standard-library package, then to format a list the way -f does.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
go list [-f format] [-json[=fields]] [flags] [packages] go list -m [-f format] [-u] [-versions] [modules]
| Flag | Description |
|---|---|
-f format |
Print each package using a text/template with the Package struct as data (or Module with -m). |
-json |
One JSON object per package. -json=ImportPath,Dir limits the fields. |
-deps |
Include all dependencies, not just the named packages, in dependency order. |
-test |
Also list the test packages and generated test main packages. |
-find |
Do not resolve imports, which makes it fast. Good for expanding patterns. |
-e |
Report errors inside the output instead of failing. |
-export |
Include the compiled export file path (Export field). |
-compiled |
Include generated Go files and cgo output in CompiledGoFiles. |
-m |
List modules instead of packages. all means every module in the build; -m alone prints the main module. |
-u |
With -m, show available upgrades. |
-versions |
With -m, list all known versions of a module. |
-retracted |
Include retracted versions in -versions. |
Useful Package fields
| Field | Meaning |
|---|---|
Dir, ImportPath, Name, Doc |
Where it is, its import path, package name, first sentence of the doc comment. |
Standard, Module |
Whether it is in the standard library; the owning module (Path, Version, Dir, GoMod). |
GoFiles, CgoFiles, IgnoredGoFiles, TestGoFiles, XTestGoFiles |
Source files selected (and excluded) by the current build constraints. |
Imports, Deps, TestImports |
Direct imports, all transitive dependencies, imports from tests. |
Stale, StaleReason |
Whether a rebuild is needed (best-effort). |
Error, DepsErrors |
Problems found while loading. |
Patterns: . (current), ./... (current and below), std (standard library), all (everything for the main module), cmd (toolchain commands), or import paths with ... wildcards such as example.com/shop/....
Usage notes
- List all packages:
go list ./...skipsvendor/and any directory that begins with_or., or is calledtestdata. - The
-ftemplate has helpers. Besides the standardtext/templatefunctions,joinjoins strings:{{join .Imports ", "}}. Whitespace between actions is kept, so wrap lines with{{"\n"}}when needed. - Combine with shell.
go test $(go list ./... | grep -v /integration)runs a subset of packages. In scripts, prefer-f '{{.Dir}}'to find folders. - Find outdated dependencies:
go list -m -u allmarks modules that have newer versions in brackets. See go get to upgrade. - Which packages does my binary use?
go list -deps -f '{{if not .Standard}}{{.ImportPath}}{{end}}' .shows only third-party and your own packages. - Constraints decide files.
GoFileslists the files for your currentGOOS,GOARCHand tags; files that did not match appear inIgnoredGoFiles. Run withGOOS=windows go list ...to see another target. - It may download. Listing packages from modules not yet in the cache triggers downloads, unless you use
-mod=readonly(the default) and everything is already recorded. - Edge cases. A pattern that matches nothing prints a warning and exits with status 1. Use
-efor tolerant output when you are scripting over a broken tree. go list -m -jsonis the machine-readable view ofgo.mod, includingreplacetargets and indirect flags; see go mod.
Related
- go mod, go build, go doc, go test
- Lessons: Modules, Dependencies, Text Templates