Add default completion command even if there are no other sub-commands

[marckhouzam]

This supersedes #1450 and #1392

When a program has no sub-commands, its root command can accept arguments. If we add the default "completion" command to such programs they will now have a sub-command and will no longer accept arguments.

What we do instead for this special case, is only add the "completion" command if it is being called.

We want to have the "completion" command for such programs because it will allow the completion of flags and of arguments (if provided by the program).

@scop can you confirm this is what you were hoping for?

Testing done

# Here is a program with no sub-cmds
$ cat tests/minimal.go
package main

import (
	"fmt"

	"github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
	Use: "prog",
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println("value:", value)
		fmt.Println("args:", args)
	},
}

var value string

func main() {
	rootCmd.Flags().StringVarP(&value, "value", "e", "", "value")
	rootCmd.Execute()
}

$ go build -o minimal ./tests/minimal.go

$ ./minimal
value:
args: []
$ ./minimal arg1
value:
args: [arg1]
$ ./minimal arg1 arg2
value:
args: [arg1 arg2]
$ ./minimal arg1 arg2 --value 1
value: 1
args: [arg1 arg2]

# Notice no 'completion' command visible
$ ./minimal -h
Usage:
  prog [flags]

Flags:
  -h, --help           help for prog
  -e, --value string   value

# But the completion command does exist
$ ./minimal completion -h
Generate the autocompletion script for prog for the specified shell.
See each sub-command's help for details on how to use the generated script.

Usage:
  prog completion [command]

Available Commands:
  bash        Generate the autocompletion script for bash
  fish        Generate the autocompletion script for fish
  powershell  Generate the autocompletion script for powershell
  zsh         Generate the autocompletion script for zsh

Flags:
  -h, --help   help for completion

Use "prog completion [command] --help" for more information about a command.

# Shell completion for the 'completion' command itself is not triggered,
# but it is triggered for sub-commands of 'completion'
$ ./minimal __complete compl
:0
Completion ended with directive: ShellCompDirectiveDefault
$ ./minimal __complete completion ''
bash	Generate the autocompletion script for bash
fish	Generate the autocompletion script for fish
powershell	Generate the autocompletion script for powershell
zsh	Generate the autocompletion script for zsh
:4
Completion ended with directive: ShellCompDirectiveNoFileComp

[scop]

Yep, seems to work nicely, thanks!

An observation is that as the completion command is hidden, no completions are generated for its arguments (i.e. "foo completion Tab"), but that's such a minor detail and not a result of this change I believe, that let's not get stuck with that :)

[marckhouzam]

An observation is that as the completion command is hidden, no completions are generated for its arguments (i.e. "foo completion Tab")

Nice attention to detail! The completions should work for hidden commands. In this case however, when we call the "__complete" command to get the completions, we don't create the "completion" command so its subcommands don't get completed.

Let me try to see if I can fix it.

[marckhouzam]

While working on this I ran into another completion bug for programs that don't have sub-commands.
I've opened issue #1562 and posted a fix in #1563.

I'm still looking at fixing the issue @scop reported above.

[github-actions]

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

[caarlos0]

This looks good, was just about to dig into this myself.

Thanks!

[marckhouzam]

I've let this rot for too long. Let's plan it for the next release. Come August iI will run some tests on it and make sure it is good.

[CLAassistant]

All committers have signed the CLA.

[caarlos0]

anything I can do to help getting this merged?

[marckhouzam]

I've finally re-worked this and I believe it is ready.
Please refer to the description of the PR to see the testing that I did, which shows the new behaviour.

[marckhouzam]

@jpmcb When you have moment, this is ready for review. Don't hesitate to ask for clarifications.

[jpmcb]

Closes: #1450 #1392

---

So looks like this was unintended behavior where the default completions were only available when some other commands were provided?

[jpmcb]

Just wondering what's the impact of this now taking a slice of args? Can this be made optional to still be backwards compatible for users who've adopted InitDefaultCompletionCmd? If it's fixing a bug / undefined behavior, that should be fine!

[marckhouzam]

Oh good point. I don’t recall why this function was ever exported. But since cobra does not need to be exported, it must mean that we did that for other people to call it. So good call that this is a breaking change.

we could simply make the argument an ellipsis to avoid breaking compilation. However, I feel this would be worse for programs that don’t have sub commands because we will break their behaviour because this completion command will now appear unless they pass the arguments properly.

I could create a new function instead I guess. I’ll give it some thought and post an update

Thanks for catching this

[marckhouzam]

So looks like this was unintended behavior where the default completions were only available when some other commands were provided?

It’s the default “completion” command that doesn’t get created unless other commands exist.

Say you write a tool called tooly. If tooly has any sub commands (e.g., tooly list) then cobra will automatically create tooly completion which allow users to generate the shell completion scripts.

This PR makes this happen for tools that don’t have any sub commands