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

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

Closed
rugk opened this issue Jul 9, 2021 · 4 comments
Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@rugk
Copy link

rugk commented Jul 9, 2021

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.:

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

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

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

@mknyszek mknyszek added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jul 9, 2021
@mknyszek mknyszek added this to the Backlog milestone Jul 9, 2021
@mknyszek mknyszek changed the title Single hyphen for flags - should be two hyphens -- in help/usage CLI output flag: single hyphen for flags (-) should be two hyphens (--) in help/usage CLI output Jul 9, 2021
@mknyszek mknyszek changed the title flag: single hyphen for flags (-) should be two hyphens (--) in help/usage CLI output flag: single hyphen for flags (-) should be two hyphens (--) in default help/usage CLI output Jul 9, 2021
@mknyszek
Copy link
Contributor

mknyszek commented Jul 9, 2021

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.

@mknyszek mknyszek closed this as completed Jul 9, 2021
@rugk
Copy link
Author

rugk commented Jul 9, 2021

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

cespare commented Jul 9, 2021

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

Dynom commented Jul 10, 2021

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

@golang golang locked and limited conversation to collaborators Jul 10, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

5 participants