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

Jump to bottom

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

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

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

pshem opened this issue Jun 20, 2019 · 4 comments
Labels
Documentation GoCommand cmd/go NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Unplanned

Comments

@pshem
Copy link

pshem commented Jun 20, 2019 •
edited

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 dmitshur added NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. GoCommand cmd/go labels Jun 20, 2019
@dmitshur
Copy link
Contributor

dmitshur commented Jun 20, 2019 •
edited

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
Copy link
Author

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
Copy link
Contributor

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
@seankhliao seankhliao added this to the Unplanned milestone Aug 27, 2022
@pjhades
Copy link

pjhades commented Feb 7, 2024 •
edited

To me this paragraph is confusing

The default output shows the package import path:

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

as I had no idea what the default output means. I thought it means that if given no command-line arguments this command will print the above 4 lines but apparently I was wrong. Maybe some more context could be added here to clarify.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation GoCommand cmd/go NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
Unplanned
Development

No branches or pull requests
4 participants
@pjhades @dmitshur @seankhliao @pshem