Have Cobra create 'completion' command automatically

[marckhouzam]

This PR has Cobra automatically provide a completion command at the root level if the program does not provide its own, just like for the help command. This lowers the barrier-to-entry and will make shell completion available to all Cobra users.

With this, a program developer does not need to learn or do anything about completion for users of the program to have access to shell completion for all four shells supported by Cobra.

The change is backwards-compatible, since existing handling for completion has not been changed. However, when no completion command is provided by the program, Cobra will now create a standard one.

Cobra will automatically include a --no-descriptions flag for zsh, fish and PowerShell, to allow users to turn off completion descriptions.

The PR also provides three configuration options:

1. Disable the creation of this new default completion command - for programs that:
   • don't want to provide completion, or
   • want to name the command something else, or
   • want to place the command elsewhere on the command tree.
2. Disable completion descriptions completely - for programs that just don't want to offer completion descriptions.
3. Disable the --no-descriptions flag - for programs that want to have completion descriptions enabled all the time.

[marckhouzam]

@jpmcb Do you think the idea of providing a completion command automatically is something of value? I'm not asking to merge but just to know if this suggestion has value in the maintainers' eyes. If not, we can close this.

[jpmcb]

@marckhouzam In my opinion, yes this would be useful. A frequent pattern I've seen in CLI tools is to have a completion command that can be injected into a .rc type file for completions.

I think we would want the ability for users to opt out of using this feature (for whatever reason) but otherwise, yes I think it'd be useful!

[marckhouzam]

Thanks @jpmcb for the feedback. The current PR does provide a way to opt-out of the completion command as well as a couple of other configurations (see the PR main description). 👍

[marckhouzam]

So a colleague wrote a command-line tool using Cobra recently. Looking at it I saw he hasn't implemented shell completion at all. This reminded me of this PR which would automatically add the completion command.

I was thinking it would be nice to include it in the next Cobra release if others agreed.

[github-actions]

This PR is being marked as stale due to a long period of inactivity

[marckhouzam]

Let's keep this one alive.

[jpmcb]

Hi Marc - where is this one at? I can review if it's in a good state! 😄

On initial look, this is awesome. I think auto-generating completions will be really powerful and remove steps for users to get completions into their CLIs

Just let me know what this needs and we can get it in!

[marckhouzam]

Thanks @jpmcb! This should be ready for review. You may want to pay particular attention at how I defined the new completion command options, just to make sure that is a good API.

[marckhouzam]

At the same time @jpmcb, @Luap99, how about I rename the custom_completion.go file to simply completions.go. The original name was from the early functionality that was only providing custom completions; however, when we added support for fish shell, that file learned full completion support but I didn't think about changing the name. The poor naming has been bothering me for a while. I'll push that change too, but if you disagree I'll revert.

[marckhouzam]

Done and ready.

[marckhouzam]

I had missed enabling the [flags] string in the help message for powershell completion. The last push fixed it.

[marckhouzam]

And I just updated the documentation to mention the default completion command and explain its options.

This is ready @jpmcb

[jpmcb]

LGTM! Tested this out on a few shells and on a few CLIs and I'm really excited about this one! Great work @marckhouzam and @Luap99