cmd/go: show the help message instead of suggesting "go help subcommand" when the --help/-h flag is passed

[fatih]

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

go version go1.11 darwin/amd64

Does this issue reproduce with the latest release?

yes

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

$ go env
GOARCH="amd64"
GOBIN="/Users/fatih/go/bin"
GOCACHE="/Users/fatih/Library/Caches/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/fatih/go"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/Cellar/go/1.11/libexec"
GOTMPDIR=""
GOTOOLDIR="/usr/local/Cellar/go/1.11/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
GOMOD=""
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 -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/k_/87syx3r50m93m72hvqj2qqlw0000gn/T/go-build154500786=/tmp/go-build -gno-record-gcc-switches -fno-common"

What did you do?

I asked to print the help usage of the command go list:

$ go list --help
usage: go list [-f format] [-json] [-m] [list flags] [build flags] [packages]
Run 'go help list' for details.

What did you expect to see?

I would like to see the help output instead of suggesting me to run go help list.

# example output I would like to see:
$ go list --help
usage: go list [-f format] [-json] [-m] [list flags] [build flags] [packages]

List lists the named packages, one per line.
The most commonly-used flags are -f and -json, which control the form
of the output printed for each package. Other list flags, documented below,
control more specific details.
...

What did you see instead?

It suggested to me to run go help list.

I think this is a not very user friendly output. --help (or -h) is a very common flag and is even parsed by the flag package. The go command understand that I'm seeking for a help, instead of suggesting me to run go help list, it should show me the help message.

As an example user case, suppose you run a command and somehow wrote it wrong:

$  go list -f
flag needs an argument: -f
usage: go list [-f format] [-json] [-m] [list flags] [build flags] [packages]
Run 'go help list' for details.

If the go command would support the --help/-h flags, I could press the up key on my keyboard (the shell would show the last executed command) and append the --help flag to see what's wrong:

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

List lists the named packages, one per line.
The most commonly-used flags are -f and -json, which control the form
of the output printed for each package. Other list flags, documented below,
control more specific details.

...

This example is not only about go list itself, this applies to every single subcommand of the go command. This happens so many times and I think it's counter intuitive to write a comand from scratch (i.e: go help list, go help test, ...). I don't know the origin why --help or -h is permitted and not allowed to be used, but if it's something that can be removed, I suggest we remove the restriction and show the help message instead of suggesting to call go help subcommand (for subcommand related --help messages).

[natefinch]

Yes please, I hate it when software says "Yes, I know what you mean, but you didn't say it right, here's how to say it right", rather than just doing what I ask.

[mvdan]

I think the point is to have the output text be small, to not take up the entirety of the user's screen. For example, see #26999.

Perhaps the -h output could be expanded a bit, and then say Run 'go help X' for more details..

[andybons]

@bcmills @rsc

[joestringer]

I often find myself not fully remembering the details of how various flags for different tools work, so my workflow is to start composing the command I want to run, then at the end add --help so that I can read the help text, press up to restore the command I'm composing, remove --help and add whatever the CLI arguments that I am trying to use. If Go were to adopt having --help flags for all commandline tools that would print the full help output when --help text is requested, this workflow would work much better.

[jessesimpson36]

Is this really all there is in terms of discussion on this topic? I would've thought more than 4 people would've complained about this. For me, this is a huge annoyance. I frequently make a mistake with an argument

For example, I frequently make errors on

go test -run <messy-regex-that-doesn't-work>

and then want to look up the argument.

go test --help

whoops, I used --help instead of go help.

I think the difference between my frustration, and other people's lack of frustration, might be the fact that I deal with more than 1 programming language on a day-to-day basis. I frequently context-switch between Golang, bash, python, java, helm, and C. For people who primarily program in Golang, maybe simply remembering go help is good enough. Maybe it's an IDE thing too. I work in the shell mostly. But I would guess that other more admin/devops-y kind of people would have issues with --help not printing help text.

Is that all there is to this topic? I would've expected someone in here would be strongly against supporting --help.
Would a patch be welcome?

[ianlancetaylor]

The current pattern is that go list -h or go list -help shows the supported flags, and tells you how to find more detailed information. Seeing the supported flags may be enough to solve the problem. If not, the more detailed help is available.

This is a situation where we can't possibly make everybody happy. To me the current approach doesn't seem like a terrible compromise.

[jessesimpson36]

Ok, so there are people that are against supporting --help. I won't waste my time on writing a patch. I thought this might've just been one of those topics that nobody made the time for.

[joestringer]

This proposal seems very similar to the concerns raised in this issue, and the proposal was accepted: #63659

[jessesimpson36]

I don't think these feel like similar topics in the way that solving #63659 would also solve this, but I could see how the proposal in #63659 being accepted could be seen as evidence that this issue won't move forward. The way I'd summarize this issue is that bash commands (especially coreutils commands) generally offer --help as the way to get usage information. The go command is an outlier but wants to standardize amongst go packages instead of CLI tools.

But these ideas don't need to go against eachother. --help could just output the same message that go doc <package> displays. that wouldn't go against the #63659 proposal.

[seankhliao]

#63659 proposes a specific format for --help more in line with traditional unix tools: summary line plus flags with short descriptions. see #63659 (comment)
go help will still exist for longer form content.

Given #63659's acceptance, I'll close this as won't do.