Go: flag: improve clarity of "flag provided but not defined" error message

[bradmiro]

Version: go1.13.5

I have a code snippet with a series of flags:

var (
    flag1 string
    flag2 string
)

func init() {
    flag.StringVar(&flag1, "flag1", "", "value for flag 1")
    flag.StringVar(&flag2, "flag2", "", "value for flag 2")
}

func main () {
    ...
}

After building, if this is executed in a bash shell:
./script "-flag1 value1" "-flag2 value2"
the output I see is this:

flag provided but not defined: -flag1 value1
Usage of ./script:
  -flag1 string
        value for flag1
  -flag2 string
        value for flag2

Now, this code doesn't work because of the quotes in the bash command and removing the quotes makes this work exactly as expected. This took me a while to debug as I wasn't able to initially interpret from flag provided but not defined: -flag1 value1 that the program was interpreting -flag1 value1 as the literal flag, as opposed to the flag and the value.

I might suggest one of two fixes:

1. Slightly modify the error message from
   flag provided but not defined: FLAG
   to
   flag "FLAG" provided but not defined

2. Add logic to detect common potential mistakes such as:

flag provided but not defined: FLAG
Did you mean to include <detected mistake such as space / equals sign etc>?

[bradmiro]

/cc @dmitshur

[dmitshur]

I think the first suggestion would be a good improvement. It improves clarity of the error message without adding complexity and special cases to the code.

There isn't much precedent in the flag package or elsewhere in Go to try to guess the users' intention and try to make suggestions, so I don't believe the second suggested fix is as good as the first.

/cc @robpike per owners.

[dmitshur]

I don't think this change is large enough to need to go through the proposal process (https://github.com/golang/proposal#scope), so I'll make it a regular issue for now.

[krunkosaurus]

Seems like all google searches of this issues come here first. :)

[robpike]

All this requires is changing %s to %q in the error message.

[brianonn]

The message flag provided but not defined: flag1 value1 has always tripped me up by its ambiguity. Does it mean flag1 is not defined, or does it mean that flag1 (a known flag) was provided and can take M of N known values for value, BUT the provided value1 is not defined (or known) by flag1? I'd much rather see something less ambiguous like this:

The flag 'flag1 value1' is an unknown flag.

To put it in context, it will look like this:

The flag '-linkmode' is an unknown flag.
usage: go build [-o output] [-i] [build flags] [packages]
Run 'go help build' for details.

Instead of this:

flag provided but not defined: -linkmode
usage: go build [-o output] [-i] [build flags] [packages]
Run 'go help build' for details.

The example with -linkmode makes the point very clear. Is -linkmode known but missing something I need to define there ?

[gopherbot]

Change https://golang.org/cl/224017 mentions this issue: cmd/go, flag: make undefined flag msg less ambiguous. Fixes #36364

[gopherbot]

Change https://golang.org/cl/224018 mentions this issue: changes needed for golang/go issue 36364