Use non-shadowed help option name in error hint

Fix #2790.

Co-authored-by: Mr-Neutr0n <64578610+Mr-Neutr0n@users.noreply.github.com>

Author: kdeldycke

CHANGES.rst

@@ -40,6 +40,10 @@ Unreleased
 -   Change :class:`ParameterSource` to an :class:`~enum.IntEnum` and reorder
     its members from most to least explicit, so values can be compared to
     check whether a parameter was explicitly provided. :issue:`2879` :pr:`3248`
+-   The error hint now uses :meth:`Command.get_help_option_names` to pick
+    non-shadowed help option names, so ``Try '... -h'`` no longer points to a
+    subcommand option that shadows ``-h``. All surviving names are shown
+    (``-h/--help``). :issue:`2790` :pr:`3208`
 
 Version 8.3.2
 -------------

src/click/exceptions.py

@@ -78,8 +78,12 @@ def show(self, file: t.IO[t.Any] | None = None) -> None:
             self.ctx is not None
             and self.ctx.command.get_help_option(self.ctx) is not None
         ):
+            help_names = self.ctx.command.get_help_option_names(self.ctx)
+            # Pick the longest name (like ``--help`` over ``-h``) for
+            # readability in error messages.
             hint = _("Try '{command} {option}' for help.").format(
-                command=self.ctx.command_path, option=self.ctx.help_option_names[0]
+                command=self.ctx.command_path,
+                option=max(help_names, key=len),
             )
             hint = f"{hint}\n"
         if self.ctx is not None:

tests/test_formatting.py

@@ -1,3 +1,5 @@
+import pytest
+
 import click
 
 
@@ -246,6 +248,71 @@ def cmd(arg):
     ]
 
 
+@pytest.mark.parametrize(
+    ("help_names", "extra_options", "expected_hint"),
+    [
+        # No shadowing, longest name is picked.
+        (["-h", "--help"], [], "Try 'cli foo --help' for help."),
+        # -h shadowed by a subcommand option, --help still available.
+        (
+            ["-h", "--help"],
+            [click.option("--host", "-h")],
+            "Try 'cli foo --help' for help.",
+        ),
+        # --help shadowed, -h still available.
+        (
+            ["-h", "--help"],
+            [click.option("--help-file", "--help")],
+            "Try 'cli foo -h' for help.",
+        ),
+        # Both names shadowed: no hint line at all.
+        (
+            ["-h", "--help"],
+            [click.option("--host", "-h"), click.option("--help-file", "--help")],
+            None,
+        ),
+        # Single custom help name, not shadowed.
+        (["--man"], [], "Try 'cli foo --man' for help."),
+        # Three help names, one shadowed, longest survivor picked.
+        (
+            ["-h", "--help", "--info"],
+            [click.option("--info-file", "--info")],
+            "Try 'cli foo --help' for help.",
+        ),
+    ],
+)
+def test_formatting_usage_error_help_hint(
+    runner, help_names, extra_options, expected_hint
+):
+    """The error hint should only show non-shadowed help option names,
+    picking the longest for readability.
+
+    https://github.com/pallets/click/issues/2790
+    """
+
+    @click.group(context_settings={"help_option_names": help_names})
+    def cli():
+        pass
+
+    @cli.command()
+    @click.argument("required_arg")
+    def foo(required_arg, **kwargs):
+        pass
+
+    for option in extra_options:
+        option(foo)
+
+    result = runner.invoke(cli, ["foo"])
+    assert result.exit_code == 2
+    lines = result.output.splitlines()
+    assert lines[0] == "Usage: cli foo [OPTIONS] REQUIRED_ARG"
+    assert lines[-1] == "Error: Missing argument 'REQUIRED_ARG'."
+    if expected_hint is not None:
+        assert expected_hint in lines
+    else:
+        assert not any(line.startswith("Try ") for line in lines)
+
+
 def test_formatting_custom_type_metavar(runner):
     class MyType(click.ParamType):
         def get_metavar(self, param: click.Parameter, ctx: click.Context):