git.sr.ht/~pingoo/stdx@v0.0.0-20240218134121-094174641f6e/cobra/bash_completions.md (about)

     1  # Generating Bash Completions For Your cobra.Command
     2  
     3  Please refer to [Shell Completions](shell_completions.md) for details.
     4  
     5  ## Bash legacy dynamic completions
     6  
     7  For backward compatibility, Cobra still supports its legacy dynamic completion solution (described below).  Unlike the `ValidArgsFunction` solution, the legacy solution will only work for Bash shell-completion and not for other shells. This legacy solution can be used along-side `ValidArgsFunction` and `RegisterFlagCompletionFunc()`, as long as both solutions are not used for the same command.  This provides a path to gradually migrate from the legacy solution to the new solution.
     8  
     9  **Note**: Cobra's default `completion` command uses bash completion V2.  If you are currently using Cobra's legacy dynamic completion solution, you should not use the default `completion` command but continue using your own.
    10  
    11  The legacy solution allows you to inject bash functions into the bash completion script.  Those bash functions are responsible for providing the completion choices for your own completions.
    12  
    13  Some code that works in kubernetes:
    14  
    15  ```bash
    16  const (
    17          bash_completion_func = `__kubectl_parse_get()
    18  {
    19      local kubectl_output out
    20      if kubectl_output=$(kubectl get --no-headers "$1" 2>/dev/null); then
    21          out=($(echo "${kubectl_output}" | awk '{print $1}'))
    22          COMPREPLY=( $( compgen -W "${out[*]}" -- "$cur" ) )
    23      fi
    24  }
    25  
    26  __kubectl_get_resource()
    27  {
    28      if [[ ${#nouns[@]} -eq 0 ]]; then
    29          return 1
    30      fi
    31      __kubectl_parse_get ${nouns[${#nouns[@]} -1]}
    32      if [[ $? -eq 0 ]]; then
    33          return 0
    34      fi
    35  }
    36  
    37  __kubectl_custom_func() {
    38      case ${last_command} in
    39          kubectl_get | kubectl_describe | kubectl_delete | kubectl_stop)
    40              __kubectl_get_resource
    41              return
    42              ;;
    43          *)
    44              ;;
    45      esac
    46  }
    47  `)
    48  ```
    49  
    50  And then I set that in my command definition:
    51  
    52  ```go
    53  cmds := &cobra.Command{
    54  	Use:   "kubectl",
    55  	Short: "kubectl controls the Kubernetes cluster manager",
    56  	Long: `kubectl controls the Kubernetes cluster manager.
    57  
    58  Find more information at https://github.com/GoogleCloudPlatform/kubernetes.`,
    59  	Run: runHelp,
    60  	BashCompletionFunction: bash_completion_func,
    61  }
    62  ```
    63  
    64  The `BashCompletionFunction` option is really only valid/useful on the root command. Doing the above will cause `__kubectl_custom_func()` (`__<command-use>_custom_func()`) to be called when the built in processor was unable to find a solution. In the case of kubernetes a valid command might look something like `kubectl get pod [mypod]`. If you type `kubectl get pod [tab][tab]` the `__kubectl_customc_func()` will run because the cobra.Command only understood "kubectl" and "get." `__kubectl_custom_func()` will see that the cobra.Command is "kubectl_get" and will thus call another helper `__kubectl_get_resource()`.  `__kubectl_get_resource` will look at the 'nouns' collected. In our example the only noun will be `pod`.  So it will call `__kubectl_parse_get pod`.  `__kubectl_parse_get` will actually call out to kubernetes and get any pods.  It will then set `COMPREPLY` to valid pods!
    65  
    66  Similarly, for flags:
    67  
    68  ```go
    69  	annotation := make(map[string][]string)
    70  	annotation[cobra.BashCompCustom] = []string{"__kubectl_get_namespaces"}
    71  
    72  	flag := &pflag.Flag{
    73  		Name:        "namespace",
    74  		Usage:       usage,
    75  		Annotations: annotation,
    76  	}
    77  	cmd.Flags().AddFlag(flag)
    78  ```
    79  
    80  In addition add the `__kubectl_get_namespaces` implementation in the `BashCompletionFunction`
    81  value, e.g.:
    82  
    83  ```bash
    84  __kubectl_get_namespaces()
    85  {
    86      local template
    87      template="{{ range .items  }}{{ .metadata.name }} {{ end }}"
    88      local kubectl_out
    89      if kubectl_out=$(kubectl get -o template --template="${template}" namespace 2>/dev/null); then
    90          COMPREPLY=( $( compgen -W "${kubectl_out}[*]" -- "$cur" ) )
    91      fi
    92  }
    93  ```