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

marckhouzam · 2021-12-11T19:41:44Z

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 · 2021-12-12T20:22:15Z

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 · 2021-12-12T21:32:19Z

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 · 2021-12-14T14:54:02Z

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 · 2022-02-13T00:05:58Z

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

caarlos0 · 2022-06-29T19:09:19Z

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

Thanks!

marckhouzam · 2022-06-29T22:19:45Z

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 · 2022-07-21T02:47:56Z

All committers have signed the CLA.

caarlos0 · 2023-06-13T18:19:20Z

anything I can do to help getting this merged?

marckhouzam · 2023-06-19T19:08:29Z

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 · 2023-07-12T19:07:11Z

@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 · 2025-01-30T00:00:36Z

completions.go

 // 3- c already has a 'completion' command provided by the program.
-func (c *Command) InitDefaultCompletionCmd() {
-	if c.CompletionOptions.DisableDefaultCmd || !c.HasSubCommands() {
+func (c *Command) InitDefaultCompletionCmd(args []string) {


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!

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

I found a few cases where this would break people's use of InitDefaultCompletionCmd. For example, for Charm, looks like they call this explicitly to correct for this exact issue:

https://github.com/charmbracelet/mods/blob/b037acfe73f811839bbda8e7bdd5f711f4df9799/main.go#L334-L342

I think the right approach is to just make the args "variadic":

-func (c *Command) InitDefaultCompletionCmd(args []string) { +func (c *Command) InitDefaultCompletionCmd(args ...string) { + if args == nil { + args = []string{} + }

Then, if someone has a slice of args, they can splat them into the function with ...:

- c.InitDefaultCompletionCmd(args) + c.InitDefaultCompletionCmd(args...)

And calling it with no args still works, like for Charm's case:

rootCmd.InitDefaultCompletionCmd()

Sounds good, thanks for finding the Charms example. I’ll rework this

I have reworked this use a variadic operator so the function signature does not break existing users.
I have also added a new test to confirm that not passing any args to the InitDefaultCompletionCmd() still works and behaves properly.
And I've improved slightly the logic of how InitDefaultCompletionCmd() figures out if it has sub-commands.

marckhouzam · 2025-01-30T01:53:50Z

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

marckhouzam · 2025-02-07T15:37:54Z

@jpmcb This is ready now. Thanks again for catching the breaking change.

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, or if it is being completed itself. 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). Signed-off-by: Marc Khouzam <[email protected]>

This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [github.com/spf13/cobra](https://github.com/spf13/cobra) | require | minor | `v1.8.1` -> `v1.9.1` | --- ### Release Notes <details> <summary>spf13/cobra (github.com/spf13/cobra)</summary> ### [`v1.9.1`](https://github.com/spf13/cobra/releases/tag/v1.9.1) [Compare Source](spf13/cobra@v1.9.0...v1.9.1) ##### 🐛 Fixes - Fix CompletionFunc implementation by [@ccoVeille](https://github.com/ccoVeille) in spf13/cobra#2234 - Revert "Make detection for test-binary more universal ([#2173](spf13/cobra#2173))" by [@marckhouzam](https://github.com/marckhouzam) in spf13/cobra#2235 **Full Changelog**: spf13/cobra@v1.9.0...v1.9.1 ### [`v1.9.0`](https://github.com/spf13/cobra/releases/tag/v1.9.0) [Compare Source](spf13/cobra@v1.8.1...v1.9.0) #### ✨ Features - Allow linker to perform deadcode elimination for program using Cobra by [@aarzilli](https://github.com/aarzilli) in spf13/cobra#1956 - Add default completion command even if there are no other sub-commands by [@marckhouzam](https://github.com/marckhouzam) in spf13/cobra#1559 - Add CompletionWithDesc helper by [@ccoVeille](https://github.com/ccoVeille) in spf13/cobra#2231 #### 🐛 Fixes - Fix deprecation comment for Command.SetOutput by [@thaJeztah](https://github.com/thaJeztah) in spf13/cobra#2172 - Replace deprecated ioutil usage by [@nirs](https://github.com/nirs) in spf13/cobra#2181 - Fix --version help and output for plugins by [@nirs](https://github.com/nirs) in spf13/cobra#2180 - Allow to reset the templates to the default by [@marckhouzam](https://github.com/marckhouzam) in spf13/cobra#2229 #### 🤖 Completions - Make Powershell completion work in constrained mode by [@lstemplinger](https://github.com/lstemplinger) in spf13/cobra#2196 - Improve detection for flags that accept multiple values by [@thaJeztah](https://github.com/thaJeztah) in spf13/cobra#2210 - add CompletionFunc type to help with completions by [@ccoVeille](https://github.com/ccoVeille) in spf13/cobra#2220 - Add similar whitespace escape logic to bash v2 completions than in other completions by [@kangasta](https://github.com/kangasta) in spf13/cobra#1743 - Print ActiveHelp for bash along other completions by [@marckhouzam](https://github.com/marckhouzam) in spf13/cobra#2076 - fix(completions): Complete map flags multiple times by [@gabe565](https://github.com/gabe565) in spf13/cobra#2174 - fix(bash): nounset unbound file filter variable on empty extension by [@scop](https://github.com/scop) in spf13/cobra#2228 #### 🧪 Testing - Test also with go 1.23 by [@nirs](https://github.com/nirs) in spf13/cobra#2182 - Make detection for test-binary more universal by [@thaJeztah](https://github.com/thaJeztah) in spf13/cobra#2173 #### ✍🏼 Documentation - docs: update README.md by [@eltociear](https://github.com/eltociear) in spf13/cobra#2197 - Improve site formatting by [@nirs](https://github.com/nirs) in spf13/cobra#2183 - doc: add Conduit by [@raulb](https://github.com/raulb) in spf13/cobra#2230 - doc: azion project added to the list of CLIs that use cobra by [@maxwelbm](https://github.com/maxwelbm) in spf13/cobra#2198 - Fix broken links in active_help.md by [@vuil](https://github.com/vuil) in spf13/cobra#2202 - chore: fix function name in comment by [@zhuhaicity](https://github.com/zhuhaicity) in spf13/cobra#2216 #### 🔧 Dependency upgrades - build(deps): bump github.com/cpuguy83/go-md2man/v2 from 2.0.5 to 2.0.6 by [@thaJeztah](https://github.com/thaJeztah) in spf13/cobra#2206 - Update to latest go-md2man by [@mikelolasagasti](https://github.com/mikelolasagasti) in spf13/cobra#2201 - Upgrade `pflag` dependencies for v1.9.0 by [@jpmcb](https://github.com/jpmcb) in spf13/cobra#2233 *** Thank you to all of our amazing contributors and all the great work that's been going into the completions feature!! ##### 👋🏼 New Contributors - [@gabe565](https://github.com/gabe565) made their first contribution in spf13/cobra#2174 - [@maxwelbm](https://github.com/maxwelbm) made their first contribution in spf13/cobra#2198 - [@lstemplinger](https://github.com/lstemplinger) made their first contribution in spf13/cobra#2196 - [@vuil](https://github.com/vuil) made their first contribution in spf13/cobra#2202 - [@mikelolasagasti](https://github.com/mikelolasagasti) made their first contribution in spf13/cobra#2201 - [@zhuhaicity](https://github.com/zhuhaicity) made their first contribution in spf13/cobra#2216 - [@ccoVeille](https://github.com/ccoVeille) made their first contribution in spf13/cobra#2220 - [@kangasta](https://github.com/kangasta) made their first contribution in spf13/cobra#1743 - [@aarzilli](https://github.com/aarzilli) made their first contribution in spf13/cobra#1956 **Full Changelog**: spf13/cobra@v1.8.1...v1.9.0 </details> --- ### Configuration 📅 **Schedule**: Branch creation - Between 12:00 AM and 03:59 AM ( * 0-3 * * * ) (UTC), Automerge - Between 12:00 AM and 03:59 AM ( * 0-3 * * * ) (UTC). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Reviewed-on: https://code.forgejo.org/forgejo/runner/pulls/557 Reviewed-by: earl-warren <[email protected]> Co-authored-by: Renovate Bot <[email protected]> Co-committed-by: Renovate Bot <[email protected]>

marckhouzam mentioned this pull request Dec 11, 2021

feat(completion): add default completion hidden if there are no subcmds #1450

Closed

github-actions bot added the kind/stale label Feb 13, 2022

marckhouzam added area/shell-completion All shell completions and removed kind/stale labels Feb 24, 2022

marckhouzam added this to the 1.6.0 milestone Jun 29, 2022

marckhouzam removed this from the 1.6.0 milestone Sep 16, 2022

marckhouzam added this to the 1.8.0 milestone Apr 5, 2023

marckhouzam mentioned this pull request Apr 28, 2023

Enable builtin completion command for root command with only flags #1954

Closed

marckhouzam force-pushed the feat/compWithNoSubCmds branch from bc8a1d0 to 10702a4 Compare June 19, 2023 18:59

github-actions bot removed the area/shell-completion All shell completions label Jun 19, 2023

marckhouzam force-pushed the feat/compWithNoSubCmds branch from 10702a4 to d1660cf Compare June 19, 2023 19:01

marckhouzam force-pushed the feat/compWithNoSubCmds branch from d1660cf to b1acb50 Compare June 21, 2023 11:10

marckhouzam modified the milestones: 1.8.0, 1.9.0 Nov 15, 2023

scop mentioned this pull request Apr 8, 2024

feat(completion): add option to create default command alone #1392

Closed

marckhouzam mentioned this pull request Apr 24, 2024

Override help subcommand logic #2136

Open

marckhouzam removed this from the 1.8.1 milestone Nov 4, 2024

marckhouzam force-pushed the feat/compWithNoSubCmds branch from b1acb50 to 7260da1 Compare January 29, 2025 13:21

jpmcb reviewed Jan 30, 2025

View reviewed changes

marckhouzam force-pushed the feat/compWithNoSubCmds branch from 7260da1 to b33f75c Compare February 7, 2025 15:28

marckhouzam force-pushed the feat/compWithNoSubCmds branch from b33f75c to 3bc273c Compare February 7, 2025 15:38

jpmcb approved these changes Feb 15, 2025

View reviewed changes

jpmcb merged commit 24ada7f into spf13:main Feb 15, 2025
20 checks passed

marckhouzam deleted the feat/compWithNoSubCmds branch February 15, 2025 18:08

marckhouzam added this to the 1.9.0 milestone Feb 15, 2025

renovate bot mentioned this pull request May 2, 2025

fix(deps): update go lirlia/prel#216

Open

1 task

thaJeztah mentioned this pull request Nov 6, 2025

daemon/command: remove __dummy_command workaround for completion moby/moby#51414

Merged

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

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

Uh oh!

Conversation

marckhouzam commented Dec 11, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

scop commented Dec 12, 2021

Uh oh!

marckhouzam commented Dec 12, 2021

Uh oh!

marckhouzam commented Dec 14, 2021

Uh oh!

github-actions bot commented Feb 13, 2022

Uh oh!

caarlos0 commented Jun 29, 2022

Uh oh!

marckhouzam commented Jun 29, 2022

Uh oh!

CLAassistant commented Jul 21, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

caarlos0 commented Jun 13, 2023

Uh oh!

marckhouzam commented Jun 19, 2023

Uh oh!

marckhouzam commented Jul 12, 2023

Uh oh!

jpmcb left a comment

Choose a reason for hiding this comment

Uh oh!

jpmcb Jan 30, 2025

Choose a reason for hiding this comment

Uh oh!

marckhouzam Jan 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jpmcb Feb 6, 2025

Choose a reason for hiding this comment

Uh oh!

marckhouzam Feb 6, 2025

Choose a reason for hiding this comment

Uh oh!

marckhouzam Feb 7, 2025

Choose a reason for hiding this comment

Uh oh!

marckhouzam commented Jan 30, 2025

Uh oh!

marckhouzam commented Feb 7, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

marckhouzam commented Dec 11, 2021 •

edited

Loading

CLAassistant commented Jul 21, 2022 •

edited

Loading

marckhouzam Jan 30, 2025 •

edited

Loading