cmd/go: clarify that 'go list' without arguments lists the package in the current directory

[pshem]

What version of Go are you using (go version)?

$ go version go1.10.4 linux/amd64

Does this issue reproduce with the latest release?

Probably

What operating system and processor architecture are you using (go env)?

go env Output

$ GOARCH="amd64"
GOBIN=""
GOCACHE="/home/pshem/.cache/go-build"
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/pshem/z/source/go"
GORACE=""
GOROOT="/usr/lib/go-1.10"
GOTMPDIR=""
GOTOOLDIR="/usr/lib/go-1.10/pkg/tool/linux_amd64"
GCCGO="gccgo"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build421264384=/tmp/go-build -gno-record-gcc-switches"

What did you do?

I read the output of go help about go list, saying it will list packages. I ran go list

What did you expect to see?

I was expecting to see the list of go packages in my $GOPATH and $GOROOT, combined. Something akin to the output of python3 -c 'help("modules")'.

What did you see instead?

can't load package: package .: no Go files in /home/pshem

Enchancement request

go help, in the section for go list, should specify that only go packages in the current/specified directory will be listed. Given #17027, I'm not the only person confused by the current description of go list

[dmitshur]

Thanks for reporting. I think this behavior is documented in the current version of Go.

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

List lists the named packages, one per line.
[...]
For more about specifying packages, see 'go help packages'.

It says that list lists the named packages. If you run go list without any packages, it uses . implicitly. This is described in go help packages output in more detail:

Many commands apply to a set of packages:

	go action [packages]

Usually, [packages] is a list of import paths.
[...]
If no import paths are given, the action applies to the
package in the current directory.

Further below:

There are four reserved names for paths that should not be used
for packages to be built with the go tool:
[...]
- "all" expands to all packages found in all the GOPATH
trees. [...]

What do you think?

[pshem]

All the program outputs you've quoted match with those from my version.

This all seems very logical now that you've explained it, but I don't think a beginner gopher would figure it out. Personally, I gave up on the help file when reading the struct for errors in the middle of go help list, with the feeling that I'm too deep for the first day.

I wish go help packages came to my attention earlier... and I don't feel like it's go's fault, since packages are recommended as a help topic in the second part of go help. I think I just got unlucky to miss that help topic.

I was wondering if it were possible to show the command ran above it's output in the help file. Below are the first lines of go help list:

user@laptop: go help list
usage: go list [-e] [-f format] [-json] [build flags] [packages]

List lists the packages named by the import paths, one per line.

The default output shows the package import path:

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

If there was a command specified above the output (would that be go list all?), it might be easier to figure out.

[dmitshur]

All the program outputs you've quoted match with those from my version.

This all seems very logical now that you've explained it, but I don't think a beginner gopher would figure it out. Personally, I gave up on the help file when reading the struct for errors in the middle of go help list, with the feeling that I'm too deep for the first day.

I wish go help packages came to my attention earlier... and I don't feel like it's go's fault, since packages are recommended as a help topic in the second part of go help. I think I just got unlucky to miss that help topic.

All of the go help topics are on one page at https://golang.org/cmd/go/. By now, that page has grown to be very large, and it serves well as a reference, but not something that's a great starting point for beginners on day 1.

We're planning to improve that by creating better-organized documentation that serves as a guide (/cc @rsc), and I hope that work will address this issue you've raised.