Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Have Cobra create 'completion' command automatically #1192

Merged
merged 1 commit into from Feb 15, 2021

Conversation

@marckhouzam
Copy link
Contributor

@marckhouzam marckhouzam commented Aug 17, 2020

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.
custom_completions.go Outdated Show resolved Hide resolved
custom_completions.go Show resolved Hide resolved
custom_completions.go Show resolved Hide resolved
@marckhouzam marckhouzam force-pushed the feat/cobraCompletionCommand branch from e24bc4b to c07c201 Aug 23, 2020
@marckhouzam marckhouzam force-pushed the feat/cobraCompletionCommand branch from c07c201 to 76bb647 Sep 9, 2020
@marckhouzam
Copy link
Contributor Author

@marckhouzam marckhouzam commented Sep 16, 2020

@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
Copy link
Collaborator

@jpmcb jpmcb commented Sep 22, 2020

@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
Copy link
Contributor Author

@marckhouzam marckhouzam commented Sep 22, 2020

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
Copy link
Contributor Author

@marckhouzam marckhouzam commented Oct 28, 2020

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
Copy link

@github-actions github-actions bot commented Dec 28, 2020

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

@marckhouzam
Copy link
Contributor Author

@marckhouzam marckhouzam commented Dec 28, 2020

Let's keep this one alive.

@jpmcb
Copy link
Collaborator

@jpmcb jpmcb commented Feb 14, 2021

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
Copy link
Contributor Author

@marckhouzam marckhouzam commented Feb 14, 2021

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.

custom_completions.go Outdated Show resolved Hide resolved
@marckhouzam
Copy link
Contributor Author

@marckhouzam marckhouzam commented Feb 14, 2021

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 marckhouzam force-pushed the feat/cobraCompletionCommand branch from e58b540 to 75ce117 Feb 14, 2021
@marckhouzam
Copy link
Contributor Author

@marckhouzam marckhouzam commented Feb 14, 2021

Done and ready.

@marckhouzam marckhouzam force-pushed the feat/cobraCompletionCommand branch from 75ce117 to 272c13d Feb 14, 2021
@marckhouzam
Copy link
Contributor Author

@marckhouzam marckhouzam commented Feb 14, 2021

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

Make it easier for programs to provide shell completion by creating
the 'completion' command automatically.

If a 'completion' command is already provided by the program, Cobra
will use that one instead.

Signed-off-by: Marc Khouzam <marc.khouzam@montreal.ca>
@marckhouzam marckhouzam force-pushed the feat/cobraCompletionCommand branch from 272c13d to 668edc9 Feb 14, 2021
@marckhouzam
Copy link
Contributor Author

@marckhouzam marckhouzam commented Feb 14, 2021

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

This is ready @jpmcb

jpmcb
jpmcb approved these changes Feb 15, 2021
Copy link
Collaborator

@jpmcb jpmcb left a comment

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

@jpmcb jpmcb merged commit b312f0a into spf13:master Feb 15, 2021
7 checks passed
@marckhouzam marckhouzam deleted the feat/cobraCompletionCommand branch Feb 15, 2021
MichaelEischer added a commit to MichaelEischer/restic that referenced this issue Jul 10, 2021
The most noteworthy change seems to be

spf13/cobra#1192
Have Cobra create 'completion' command automatically
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

3 participants