flag: single hyphen for flags (-) should be two hyphens (--) in default help/usage CLI output

[rugk]

This is an error in Caddy, which uses your standard library for CLI arguments/flags. And as such, I was told to report this here. 🙃

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

No idea.

Does this issue reproduce with the latest release?

N/A

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

x64_x86
Linux, Fedora Workstation 34

It's Caddy I'm using that uses your standard library here:
Caddy v2.4.3 h1:Y1FaV2N4WO3rBqxSYA8UZsZTQdN+PwcoOcAiZTM8C0I=

What did you do?

Consider this command:

$ podman run --rm -v $PWD:/test:z caddy caddy help validate 
Loads and provisions the provided config, but does not start running it.
This reveals any errors with the configuration through the loading and
provisioning stages.

usage:
  caddy validate --config <path> [--adapter <name>]

flags:
  -adapter string
    	Name of config adapter
  -config string
    	Input configuration file

Full documentation is available at:
https://caddyserver.com/docs/command-line

Or this horrible typo I made:

$ podman run --rm --name caddyformat -v $PWD:/test:z caddy caddy fmt -override /test/Caddyfile  
flag provided but not defined: -override
Usage of format:
  -overwrite
    	Overwrite the input file with the results

What did you expect to see?

It is a very common pattern to use one hyphen for single-letter (short parameters) and two for longer arguments,

See e.g.
https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html
various Stackexchange questions (on literally any platform of them 😜 )
https://en.wikipedia.org/wiki/Command-line_interface#Option_conventions_in_Unix-like_systems

As such, I'd propose to always use --the-two-hypens when referring to a flag in the help output.

What did you see instead?

In the short summary you are writing --config e.g., but in the full flag (usually also called parameter, but that is irrelevant IMHO) list below, you list it as -config, i.e. a single hyphen. Even when your software can handle both, it is somewhat inconsistent and confusing IMHO.

---

Adopted/copied from downstream caddyserver/caddy#4240

---

The issue seems to lie here, e.g.:

go/src/flag/flag.go

Line 571 in 2701515

fmt.Fprintf(f.Output(), "Usage of %s:\n", f.name)

go/src/flag/flag.go

Line 963 in 2701515

return false, f.failf("flag provided but not defined: -%s", name)

I.e. there you use the “wrong” number of hyphens.

[mknyszek]

Thanks for the issue, but I'm not sure I see what the source of confusion is. Both forms of flag are accepted (both - and -- prefixes), so I don't think it matters much which is shown by default.

Since #45484 asks for exactly the same thing and was closed, I'm going to close this as well.

Also note that the flag package lets you override this (that is, what is displayed) if you want. If you think caddy should do something different, you can ask them to override flag.Usage and not use flag.PrintDefaults.

[rugk]

Both forms of flag are accepted (both - and -- prefixes), so I don't think it matters much which is shown by default.

Well… what matters to me personally is at least consistency, i.e. you should show the same thing always. (But not the one thing in the header and later one the - version.)
IMHO -- as that is way more accepted as a standards, so I'd opt for this…

[cespare]

Caddy has chosen to write out the flags using two hyphens in the prose section but it's using flag.PrintDefaults, which uses one hyphen:

usage:
  caddy validate --config <path> [--adapter <name>]      <--- "--config" comes from caddy

flags:
  -adapter string
    	Name of config adapter
  -config string                                         <--- "-config" is printed by flag.PrintDefaults
    	Input configuration file

That is, Caddy is the source of the inconsistency here. Either Caddy should use the flag convention of referring to flag names with one hyphen everywhere, or it should not use flag.PrintDefaults to print the flag names and instead handle printing them itself using two hyphens.

IMHO -- as that is way more accepted as a standards, so I'd opt for this…

Go's flag package does not use getopt-style syntax. If you prefer that, use a different flag parsing package.

[Dynom]

Perhaps you can point them to https://pkg.go.dev/rsc.io/getopt. It should play well with the flag package.