help: need to simplify help-related code #1136
Assignees
Labels
code health
Improve code readability, simplify maintenance and so on
Comments
elhimov
added a commit
that referenced
this issue
Apr 3, 2025
elhimov
added a commit
that referenced
this issue
Apr 3, 2025
elhimov
added a commit
that referenced
this issue
Apr 3, 2025
elhimov
added a commit
that referenced
this issue
Apr 3, 2025
elhimov
added a commit
that referenced
this issue
Apr 3, 2025
elhimov
added a commit
that referenced
this issue
Apr 3, 2025
elhimov
added a commit
that referenced
this issue
Apr 3, 2025
elhimov
added a commit
that referenced
this issue
Apr 3, 2025
1 task
elhimov
added a commit
that referenced
this issue
Apr 17, 2025
elhimov
added a commit
that referenced
this issue
Apr 17, 2025
In order to simplify help implementation: - main help command is implemented in a way similar to the other commands (internal/external variation of help command is handled with the common handler cmd.RunModuleFunc) - help for every external command is tied to a command itself over cmd.SetHelp rather than add separate help subcommand to the main help command (it allows to get help uniformly for internal and external commands) - corresponding Cobra commands are created for all available external commands rather than only for the invoked one (it is needed for the uniform handling mentioned above) In addition: - completion for help command is improved (also suggested/completed subcommands, if any) - external commands are also implemented over the common handler cmd.RunModuleFunc to reduce code duplication Close #1136
elhimov
added a commit
that referenced
this issue
Apr 17, 2025
In order to simplify help implementation: - main help command is implemented in a way similar to the other commands (internal/external variation of help command is handled with the common handler cmd.RunModuleFunc) - help for every external command is tied to a command itself over cmd.SetHelp rather than add separate help subcommand to the main help command (it allows to get help uniformly for internal and external commands) - corresponding Cobra commands are created for all available external commands rather than only for the invoked one (it is needed for the uniform handling mentioned above) In addition: - completion for help command is improved (also suggested/completed subcommands, if any) - external commands are also implemented over the common handler cmd.RunModuleFunc to reduce code duplication Close #1136
elhimov
changed the title
elhimov
added
code health
elhimov
added a commit
that referenced
this issue
Apr 18, 2025
Following changes are applied: - the main help command is implemented in a way similar to the other commands (choice between internal and external variation of the command is handled with the common handler cmd.RunModuleFunc) - help for every external command is tied to a command itself over cmd.SetHelp function rather than add separate help subcommand to the main help command (it allows to obtain help for internal and external commands uniformly) - corresponding Cobra commands are created for all available external commands rather than only for the invoked one (being combined with the uniform handling mentioned above it allows to make implementation of the internal variation of help command trivial) In addition: - `tt help` completion is improved (also suggest completion for subcommands, if any) - external commands are also implemented over the common handler cmd.RunModuleFunc to reduce code duplication Close #1136
elhimov
added a commit
that referenced
this issue
Apr 21, 2025
elhimov
added a commit
that referenced
this issue
Apr 21, 2025
Following changes are applied: - the main help command is implemented in a way similar to the other commands (choice between internal and external variation of the command is handled with the common handler cmd.RunModuleFunc) - help for every external command is tied to a command itself over cmd.SetHelp function rather than add separate help subcommand to the main help command (it allows to obtain help for internal and external commands uniformly) - corresponding Cobra commands are created for all available external commands rather than only for the invoked one (being combined with the uniform handling mentioned above it allows to make implementation of the internal variation of help command trivial) In addition: - `tt help` completion is improved (also suggest completion for subcommands, if any) - external commands are also implemented over the common handler cmd.RunModuleFunc to reduce code duplication Close #1136
elhimov
added a commit
that referenced
this issue
May 7, 2025
elhimov
added a commit
that referenced
this issue
May 7, 2025
Following changes are applied: - the main help command is implemented in a way similar to the other commands (choice between internal and external variation of the command is handled with the common handler cmd.RunModuleFunc) - help for every external command is tied to a command itself over cmd.SetHelp function rather than add separate help subcommand to the main help command (it allows to obtain help for internal and external commands uniformly) - corresponding Cobra commands are created for all available external commands rather than only for the invoked one (being combined with the uniform handling mentioned above it allows to make implementation of the internal variation of help command trivial) - external commands are also implemented over the common handler cmd.RunModuleFunc to reduce code duplication Close #1136
elhimov
added a commit
that referenced
this issue
May 10, 2025
Following changes are applied: - the main help command is implemented in a way similar to the other commands (choice between internal and external variation of the command is handled with the common handler cmd.RunModuleFunc) - help for every external command is tied to a command itself over cmd.SetHelp function rather than add separate help subcommand to the main help command (it allows to obtain help for internal and external commands uniformly) - corresponding Cobra commands are created for all available external commands rather than only for the invoked one (being combined with the uniform handling mentioned above it allows to make implementation of the internal variation of help command trivial) - external commands are also implemented over the common handler cmd.RunModuleFunc to reduce code duplication Close #1136
elhimov
added a commit
that referenced
this issue
May 10, 2025
Following changes are applied: - the main help command is implemented in a way similar to the other commands (choice between internal and external variation of the command is handled with the common handler cmd.RunModuleFunc) - help for every external command is tied to a command itself over cmd.SetHelp function rather than add separate help subcommand to the main help command (it allows to obtain help for internal and external commands uniformly) - corresponding Cobra commands are created for all available external commands rather than only for the invoked one (being combined with the uniform handling mentioned above it allows to make implementation of the internal variation of help command trivial) - external commands are also implemented over the common handler cmd.RunModuleFunc to reduce code duplication Close #1136
elhimov
added a commit
that referenced
this issue
May 11, 2025
Following changes are applied: - the main help command is implemented in a way similar to the other commands (choice between internal and external variation of the command is handled with the common handler cmd.RunModuleFunc) - help for every external command is tied to a command itself over cmd.SetHelp function rather than add separate help subcommand to the main help command (it allows to obtain help for internal and external commands uniformly) - corresponding Cobra commands are created for all available external commands rather than only for the invoked one (being combined with the uniform handling mentioned above it allows to make implementation of the internal variation of help command trivial) - external commands are also implemented over the common handler cmd.RunModuleFunc to reduce code duplication Close #1136
dmyger
pushed a commit
that referenced
this issue
May 14, 2025
dmyger
pushed a commit
that referenced
this issue
May 14, 2025
Following changes are applied: - the main help command is implemented in a way similar to the other commands (choice between internal and external variation of the command is handled with the common handler cmd.RunModuleFunc) - help for every external command is tied to a command itself over cmd.SetHelp function rather than add separate help subcommand to the main help command (it allows to obtain help for internal and external commands uniformly) - corresponding Cobra commands are created for all available external commands rather than only for the invoked one (being combined with the uniform handling mentioned above it allows to make implementation of the internal variation of help command trivial) - external commands are also implemented over the common handler cmd.RunModuleFunc to reduce code duplication Close #1136
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Current implementation of help functionality looks quite tricky.
First, brief description of the ways Cobra provides to customize help behavior. There are multiple of them and they can be used in any combination:
Custom help command:
By default Cobra automatically generates 'help' command so we can launch
tt help [CMD [SUBCMD]]w/o any additional efforts (we don't need to create 'help' command). Being executed the default 'help' command just find corresponding command object and call its help function. Can be overridden withcmd.setHelpCommand(customHelpCmd)(usually it is overridded for the root command because 'help' is expected to be launched as top-level command).Custom help function:
By default Cobra uses command help template to generate help string out of command object. Can be overridden for the certain command with
cmd.setHelpFunc(customHelpFunc).Custom help template:
By default Cobra obtains template from the parent command if any or use the predefined one. Usually single template is defined for the root command and it is used with all commands. Can be overridden with
cmd.setHelpTemplate(customHelpTemplate).Custom usage func/template:
Used by default help func/template and work similar. They don't bring any new concept and are mentioned just for the reference.
Problem items:
Considering that Cobra doesn't provide API to get help command it turns out that there are only 2 "legal" approaches: we should either use the default help command as-is or define a custom one with
cmd.setHelpCommand(customHelpCmd)if the default one doesn't meet our expectations. However current implementation follows the other approach:util.GetHelpCommandobtain help command using the knowledge of Cobra's internals)rootCmd.InitDefaultHelpCmd()(usually we should not know about this function because Cobra calls it internally in a proper place, but the mentioned internals-knowledge forces us to call it beforeutil.GetHelpCommandto make it work)Customization in a such strange way looks like an attempt to reuse functionality of the default help command at any cost but I doubt that it worth it.
Handling of variation between internal and external help command has its own implementation though there is nothing special in it comparing to the other commands and common code could be reused.
There is duplication of Cobra's functionality that parses help flags.
Suggested solution:
Consider implementation of custom help command in a way similar to the other commands. It will allow both:
util.GetHelpCommandhackConsider implementation of getting help for external command over
cmd.Help()so help command could handle external and internal commands uniformly. It will allow both:The text was updated successfully, but these errors were encountered: