Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
pshem opened this issue Jun 20, 2019 · 3 comments

Comments

@pshem
Copy link

@pshem pshem commented Jun 20, 2019

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

@pshem pshem changed the title go list description should specify that packages are only listed from the specified directory go list description should specify that packages are only listed from the current directory Jun 20, 2019
@dmitshur dmitshur changed the title go list description should specify that packages are only listed from the current directory cmd/go: go list description should specify that packages are only listed from the current directory Jun 20, 2019
@dmitshur

This comment has been minimized.

Copy link
Member

@dmitshur dmitshur commented Jun 20, 2019

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

This comment has been minimized.

Copy link
Author

@pshem pshem commented Jun 21, 2019

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

This comment has been minimized.

Copy link
Member

@dmitshur dmitshur commented Jun 21, 2019

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.

@bcmills bcmills changed the title cmd/go: go list description should specify that packages are only listed from the current directory cmd/go: clarify that 'go list' without arguments lists the package in the current directory Jun 26, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.