Usage() prints too much, how to get just one usage line?

[cben]

Currently Usage() / UsageString() is almost the same as Help(). As far as I can tell, it returns everything except the Long description on top:

Full example at https://play.golang.org/p/TLpJfHJ2fG5

== SubCmd.Help() ==
Does bla bla

Usage:
  prog cmd ARG [OTHER_ARG] [flags]

Flags:
      --force   Do unwise things.

Global Flags:
  -v, --verbose   verbose output
== SubCmd.Usage() ==
Usage:
  prog cmd ARG [OTHER_ARG] [flags]

Flags:
      --force   Do unwise things.

Global Flags:
  -v, --verbose   verbose output

I don't find this useful.
Yes, technically listing all flags is necessary to fully answer the question "how can I use this command". However, even the Long field usually contains relevant info! It explains what the command does, and AFAIK that's the only place we can currently stuff descriptions of positional args (#571). So if I wanted a full answer I'd use Help().

I want a compact message that's suitable to print on wrong invocations (especially wrong positional arguments). Something that's useful as a reminder; user can always --help for more details. In these cases I'd want:

Usage:  prog cmd ARG [OTHER_ARG] [flags]

I can get it now by peeking at SubCmd.Use but that's bad:

• it might or might not contain [flags] and cobra normalizes that when it prints usage.
• directly accessing it would not support extensions like Ability to define arguments as well (like flags) #378 / Add '[args]' and 'Valid Args:' to --help #842.

Backward compatibility

Re-defining Usage/UsageString now will I think do more harm than good.
But how do you feel of adding new method(s), e.g. ShortUsageString and optionally ShortUsage?

[Luap99]

You can set a Usage template with cmd.SetUsageTemplate()

[cben]

Nice, almost there!

• There is already a .UseLine() method! This is great, I can call it manually.
  (see updated example https://play.golang.org/p/TLpJfHJ2fG5)

• RootCmd.SetUsageTemplate("Usage: {{.UseLine}}\n") makes invocation errors & .Usage() do what I want, but alas it breaks --help & .Help(), because the default HelpTemplate() relies on UsageString to do most of its job 😦

• SetUsageFunc will have same effect, because UsageString is implemented by running UsageFunc while capturing stderr & stdout.

• I could SetHelpTemplate to contain everything UsageTemplate now contains, but that's very unwieldy.

• How about duplicating the template content by default, so that SetUsageTemplate will not affect Help? I'll send a PR.

[lukasmalkmus]

@cben Stumbled across the same problem. That's why https://github.com/cli/cli heavily worked around that. Would love to see an upcoming PR. Ping me if you need help.

[github-actions]

This issue is being marked as stale due to a long period of inactivity

[johnSchnake]

Seemed like there was some interest here but nothing ever moved forward. Going to leave stale tag but if someone wants to pick this up it seems like it would be well received.

[johnSchnake]

So after looking at this again and a peek at the code I think the solution is much more narrow for you to work around this.

You had mentioned correctly that the help function relies heavily on what the usage string is. However, if there is a helpTemplate it will use that instead. You mentioned not wanting to copy the whole usage template because it was unwieldy. But you can grab the template first before reassigning it:

c.SetHelpTemplate(c.UsageTemplate())
c.SetUsageTemplate(<your custom template>)

Going to close this; feel free to reopen if you feel there is more to discuss.