Pass arguments to the help function

[marckhouzam]

Fixes #2154

This PR makes sure that when Cobra calls HelpFunc()(cmd, args), the proper arguments are passed to the function. With this, when the help function is overridden, the new function can choose to print the help output based on what the args are.

For example, say I write my own ls program, I could override the help function using SetHelpFunc() so that

• ls -h would print List the content of the current directory
• ls mydir -h would instead print List the content of the "mydir" directory

This PR fixed the two cases where the help function is called:

1. when using the --help/-h flag (e.g., prog sub arg1 -h)
2. when using the help command (e.g., prog help sub arg1)

Another value of this fix is for programs that use plugins and want to ask the plugin what the help output should be. For instance the tanzu CLI does this, where if I type tanzu help cluster list the help function will call the cluster plugin but needs to tell it that it needs the help for the list command. This list argument needs this PR to get passed to the help function. One can see how the tanzu code had to use os.Args to work around this bug.

Unit tests have been added which also illustrate the different cases that that PR fixes. A test program is provided in #2154 to show the problem before this PR.

Please refer to a couple of comments I will add in the PR review for a concern about backwards-compatibility.

[github-actions[bot]]

This PR exceeds the recommended size of 200 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

[marckhouzam]

@jpmcb Could you have a look at this? It is 7 lines of actual code with the rest being tests.

@nirs I've seen recently how you are providing some great help to the Cobra project and your input here would be appreciated.

[nirs]

This PR fixed the two cases where the help function is called:

1. when using the --help/-h flag (e.g., prog sub arg1 -h)
2. when using the help command (e.g., prog help sub arg1)

I think this change is not needed and we can keep the current behavior, and fix the case of the more common and useful -h/--help.

Another value of this fix is for programs that use plugins and want to ask the plugin what the help output should be. For instance the tanzu CLI does this, where if I type tanzu help cluster list the help function will call the cluster plugin but needs to tell it that it needs the help for the list command. This list argument needs this PR to get passed to the help function.

Why would someone type:

tanzu help cluster list

and then type work hard to remove the help command to run the actual command, instead of adding -h to the actual command:

tanzu cluster list -h

and finally remove the -h for running the actual command?

I guess tanszu smart help works both for help and -h/--help, so if we fix -h,--help, we can remove the workarounds?

It we spend time on the help command, we should make it easy to show different content for "help command". For example try git log -h and git help log. This is the biggest problems with Go tools - the online help is not good enough and we never have manual pages.

[github-actions[bot]]

This PR exceeds the recommended size of 200 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

[github-actions[bot]]

This PR exceeds the recommended size of 200 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

[marckhouzam]

This PR fixed the two cases where the help function is called:

1. when using the --help/-h flag (e.g., prog sub arg1 -h)
2. when using the help command (e.g., prog help sub arg1)

I think this change is not needed and we can keep the current behavior, and fix the case of the more common and useful -h/--help.

Answered here: https://github.com/spf13/cobra/pull/2158#discussion_r1635050426

Another value of this fix is for programs that use plugins and want to ask the plugin what the help output should be. For instance the tanzu CLI does this, where if I type tanzu help cluster list the help function will call the cluster plugin but needs to tell it that it needs the help for the list command. This list argument needs this PR to get passed to the help function.

Why would someone type:

tanzu help cluster list

and then type work hard to remove the help command [...]

I agree that the help command is not very useful and I personally never use it. However, I still have to make it work for others who may use it. 😄

I guess tanzu smart help works both for help and -h/--help, so if we fix -h,--help, we can remove the workarounds?

The same override of HelpFunc() does work for both help and -h/--help but that is because Cobra uses the same HelpFunc() in both cases. So we need to fix it for both cases.

It we spend time on the help command, we should make it easy to show different content for "help command". For example try git log -h and git help log. This is the biggest problems with Go tools - the online help is not good enough and we never have manual pages.

This sounds like a good idea. Programs using Cobra can do this already by overriding the help command completely, and provide something different between help and -h. But maybe we can make it easier for them so that we can promote the idea of having different output in both cases. I like the example of git help log vs git log -h that you provide. It would be great if Cobra could guide projects to do something like that.