cli: FlagErrorFunc: don't print long usage output for invalid flags

When trying to use an invalid flag, the CLI currently prints the a short
error message, instructions to use the `--help` flag to learn about the
correct usage, followed by the command's usage output.

While this is a common convention, and may have been a nice gesture when
docker was still young and only had a few commands and options ("you did
something wrong, but here's an overview of what you can use"), that's no
longer the case, and many commands have a _very_ long output.

The result of this is that the error message, which is the relevant
information in this case - "You mis-typed something" - is lost in the
output, and hard to find (sometimes even requiring scrolling back).

The output is also confusing, because it _looks_ like something ran
successfully (most of the output is not about the error!).

Even further; the suggested resolution (try `--help` to see the correct
options) is rather redundant, because running teh command with `--help`
produces _exactly_ the same output as was just showh, baring the error
message. As a fun fact, due to the usage output being printed, the
output even contains not one, but _two_ "call to actions";

- `See 'docker volume --help'.` (under the erro message)
- `Run 'docker volume COMMAND --help' for more information on a command.`
  (under the usage output)

In short; the output is too verbose, confusing, and doesn't provide
a good UX. Let's reduce the output produced so that the focus is on the
important information.

This patch:

- Changes the usage to the short-usage.
- Prefixes the error message with the binary / root-command name
  (usually `docker:`) to be consistent with `unknon command`, and helps
  to distinguish where the message originated from (the `docker` CLI in
  this case).
- Adds an empty line between the error-message and the "call to action"
  (`Run 'docker volume --help' ...` in the example below). This helps
  separating the error message ("unkown flag") from the call-to-action.

Before this patch:

    docker volume --no-such-flag
    unknown flag: --no-such-flag
    See 'docker volume --help'.

    Usage:  docker volume COMMAND

    Manage volumes

    Commands:
      create      Create a volume
      inspect     Display detailed information on one or more volumes
      ls          List volumes
      prune       Remove unused local volumes
      rm          Remove one or more volumes
      update      Update a volume (cluster volumes only)

    Run 'docker volume COMMAND --help' for more information on a command.

With this patch:

    docker volume --no-such-flag
    docker: unknown flag: --no-such-flag

    Usage:  docker volume COMMAND

    Run 'docker volume --help' for more information

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2024-07-04 23:45:30 +02:00
Родитель ce4469a696
Коммит f28fc7f82f
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 76698F39D527CE8C
2 изменённых файлов: 2 добавлений и 6 удалений

Просмотреть файл

@ -92,12 +92,8 @@ func FlagErrorFunc(cmd *cobra.Command, err error) error {
return nil return nil
} }
usage := ""
if cmd.HasSubCommands() {
usage = "\n\n" + cmd.UsageString()
}
return StatusError{ return StatusError{
Status: fmt.Sprintf("%s\nSee '%s --help'.%s", err, cmd.CommandPath(), usage), Status: fmt.Sprintf("%s\n\nUsage: %s\n\nRun '%s --help' for more information", err, cmd.UseLine(), cmd.CommandPath()),
StatusCode: 125, StatusCode: 125,
} }
} }

Просмотреть файл

@ -78,6 +78,6 @@ func TestGlobalHelp(t *testing.T) {
}) })
assert.Assert(t, is.Equal(res2.Stdout(), "")) assert.Assert(t, is.Equal(res2.Stdout(), ""))
assert.Assert(t, is.Contains(res2.Stderr(), "unknown flag: --badopt")) assert.Assert(t, is.Contains(res2.Stderr(), "unknown flag: --badopt"))
assert.Assert(t, is.Contains(res2.Stderr(), "See 'docker --help")) assert.Assert(t, is.Contains(res2.Stderr(), "Run 'docker --help' for more information"))
}) })
} }