Format of "mycommand --help" and "help mycommand"

[tschoellhorn]

I use Spring Boot 4.0.3.

When defining a Command with the @Command-Annotation it is possible to set a "help"-text. Currently this text is displayed when using the "--help" option. But: This text is displayed without parameters, options and synopsis. Consider this case:

@CommandGroup(name = "samples", prefix = "samples")
@Component
public class SampleCommand {
	@Command(
		name = "bar", 
		description = "Description of 'bar'", 
		help = "Help of 'bar'")
	public void bar(
		@Arguments List<Integer> values, 
		@Option String name) {
		System.out.println("do it : " + name);
		System.out.println("values: " + values);
	}
}

When running samples bar --help the output is:

Help of 'bar'

But when running help samples bar this output is produced:

NAME
        samples bar - Description of 'bar'

SYNOPSIS
        samples bar --name String --help

OPTIONS
        --name String

        [Optional, default = ]

        --help or -h
        help for samples bar
        [Optional]

In the later variant the text of the @Command.help is completely ignored. I suggest the following:

1.) The output of both "help" variants should be same - the base for that could be the help samples bar version.
2.) The @Command.help text should be integrated in that output.

I saw other issues which implicitely mentioned the same idea. This would streamline the help output.

[czpilar]

The two outputs come from two independent renderers that share nothing.

--help is handled in AbstractCommand.execute(), which prints getHelp() verbatim - the @Command(help = ...) string, or the default name(aliases): description from Command.getHelp() when it is not set. It never looks at the command's options or arguments.

help <command> is handled in Help.getHelpMessageForCommand(), which builds NAME / SYNOPSIS / OPTIONS / ARGUMENTS / ALIASES from the command metadata and never reads getHelp().

So both halves of the report hold: --help cannot show a synopsis, and help <command> cannot show the custom help text.

Reachability on main

Worth noting for the repro - on main the --help half currently fails for a grouped command before any of this is reached:

'samples bar --help'      -> IllegalArgumentException: Option '--help' requires a value
'samples bar -h'          -> IllegalArgumentException: Option '-h' requires a value
'samples bar --help=true' -> parsed

That is #1368, fixed by #1369. The output shown in the report is reachable for a top-level command, which takes a different path in DefaultCommandParser.

Suggested direction

Extract the rendering into a single component used by both paths, and feed getHelp() into it as a DESCRIPTION section, omitted when unset:

NAME
        samples bar - Description of 'bar'

DESCRIPTION
        Help of 'bar'

SYNOPSIS
        ...

That keeps description and help distinct - a one-liner for the command list, a longer text for the detailed view - instead of help replacing the whole output.

Depends on work already in flight

Three open PRs touch exactly these files, so this should land after them:

• Report variadic arguments in the help message #1372 changes Help.appendSynopsis() and Help.appendArguments() and adds a golden-output test; moving that code into a renderer now would conflict throughout
• Fix detection of the implicit help option #1371 changes the --help dispatch branch in AbstractCommand.execute()
• Fix implicit --help option for sub-commands #1369 makes --help reach the command at all for grouped commands, as above

Any format change also invalidates the expected outputs in HelpTests, including the one #1372 adds.

Happy to pick this up once those are merged and the direction here is agreed.