git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [RFC] usage_msg_opt() and _optf() must die

From
Eric Sunshine <sunshine@sunshineco.com>
Date
Aug 6, 2024, 17:38 UTC
Message-ID
<CAPig+cSobEaKf3G4OQ7wHYMXTB23mHdwk2sJi5t9+X3ZX_xcLA@mail.gmail.com>
In-Reply-To
<xmqqmslptw3u.fsf_-_@gitster.g>
On Tue, Aug 6, 2024 at 1:11 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 7 quoted lines
> Junio C Hamano <gitster@pobox.com> writes:
> > Patrick Steinhardt <ps@pks.im> writes:
> >> I always have to wonder how helpful it really is to print the usage
> >> information in such a context. I feel that it is too distracting because
> >> in many cases, we end up printing dozens of lines of options that drown
> >> out the single line of information that the user actually cares for,
> >> namely why the command has failed.

Thank you, Patrick, for voicing this concern; I nearly did so myself upon reading this series. I always find it very user-hostile when the program dumps the entire usage text, thus forcing the user to sift through a bunch of noise, when it should instead just be printing a simple explanation of the problem to help the user correct the invocation. (It's even more frustrating when a program dumps the usage text but doesn't even bother explaining the problem[*], as if the user will somehow be able to intuit what went wrong.)

[*]: https://lore.kernel.org/git/CAPig+cSK+wLPUDuGf1d41J_F5jQS+J=a=7kHQLV07-ZKZW9GsA@mail.gmail.com/
Show 16 quoted lines
> Yes.  I do not think I found it useful to give the single-line
> message, blank line, followed by the full usage text even a single
> time myself.
>
> I am very much tempted to suggest us do this.
>
>  void NORETURN usage_msg_opt(const char *msg,
> -                  const char * const *usagestr,
> -                  const struct option *options)
> +                  const char * const *usagestr UNUSED,
> +                  const struct option *options UNUSED)
>  {
> -       die_message("%s\n", msg); /* The extra \n is intentional */
> -       usage_with_options(usagestr, options);
> +       die("%s", msg);
>  }

As a minimal "fix" to eliminate the user-hostile behavior, I would be very much in favor of this change.

(Retiring `usage_msg_opt` altogether would be even better, but is much more invasive.)

Previous: Junio C HamanoNext: Junio C Hamano
Message 6 of 16 in “make "too many arguments" a bit more useful”
  1. 0/4 make "too many arguments" a bit more usefulJunio C Hamano, Aug 6, 2024
  2. 1/4 refs: avoid "too many arguments"Junio C Hamano, Aug 6, 2024
  3. Patrick SteinhardtAug 6, 2024
  4. Junio C HamanoAug 6, 2024
  5. [RFC] usage_msg_opt() and _optf() must dieJunio C Hamano, Aug 6, 2024
  6. Eric SunshineAug 6, 2024
  7. Junio C HamanoAug 6, 2024
  8. Patrick SteinhardtAug 7, 2024
  9. Justin ToblerAug 6, 2024
  10. Martin ÅgrenAug 6, 2024
  11. refs: avoid "too many arguments"Junio C Hamano, Aug 6, 2024
  12. 2/4 cat-file: avoid "too many arguments"Junio C Hamano, Aug 6, 2024
  13. 3/4 notes: avoid "too many arguments"Junio C Hamano, Aug 6, 2024
  14. 4/4 miscellaneous: avoid "too many arguments"Junio C Hamano, Aug 6, 2024
  15. Eric SunshineAug 6, 2024
  16. Junio C HamanoAug 6, 2024

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.