From 82158677d130c2c914cb33402d2e0fda1976d7b6 Mon Sep 17 00:00:00 2001 From: Marc Khouzam Date: Mon, 4 Jan 2021 17:28:15 -0500 Subject: [PATCH] Clarify documentation for completion Signed-off-by: Marc Khouzam --- shell_completions.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/shell_completions.md b/shell_completions.md index 511b2f3ca..406866337 100644 --- a/shell_completions.md +++ b/shell_completions.md @@ -148,8 +148,8 @@ cmd := &cobra.Command{ Use: "status RELEASE_NAME", Short: "Display the status of the named release", Long: status_long, - RunE: func(cmd *cobra.Command, args []string) { - RunGet(args[0]) + Run: func(cmd *cobra.Command, args []string) { + RunStatus(args[0]) }, ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) { if len(args) != 0 { @@ -159,13 +159,14 @@ cmd := &cobra.Command{ }, } ``` -Where `getReleasesFromCluster()` is a Go function that obtains the list of current Helm releases running on the Kubernetes cluster. -Notice we put the `ValidArgsFunction` on the `status` sub-command. Let's assume the Helm releases on the cluster are: `harbor`, `notary`, `rook` and `thanos` then this dynamic completion will give results like: +Where `getReleasesFromCluster()` is a Go function that returns the list of current Helm release names running on the Kubernetes cluster. +Similarly as for `Run`, the `args` parameter represents the arguments present on the command-line, while the `toComplete` parameter represents the final argument which the user is trying to complete (e.g., `helm status th` will have `toComplete` be `"th"`); the `toComplete` parameter will be empty when the user has requested completions right after typing a space (e.g., `helm status `). Notice we put the `ValidArgsFunction` on the `status` sub-command, as it provides completions for this sub-command specifically. Let's assume the Helm releases on the cluster are: `harbor`, `notary`, `rook` and `thanos` then this dynamic completion will give results like: ```bash $ helm status [tab][tab] harbor notary rook thanos ``` + You may have noticed the use of `cobra.ShellCompDirective`. These directives are bit fields allowing to control some shell completion behaviors for your particular completion. You can combine them with the bit-or operator such as `cobra.ShellCompDirectiveNoSpace | cobra.ShellCompDirectiveNoFileComp` ```go // Indicates that the shell will perform its default behavior after completions @@ -324,7 +325,7 @@ cmd.RegisterFlagCompletionFunc(flagName, func(cmd *cobra.Command, args []string, ``` ### Descriptions for completions -`zsh`, `fish` and `powershell` allow for descriptions to annotate completion choices. For commands and flags, Cobra will provide the descriptions automatically, based on usage information. For example, using zsh: +`zsh`, `fish` and `powershell` support descriptions for completion choices. For commands and flags, Cobra will provide the descriptions automatically, based on usage information. For example, using zsh: ``` $ helm s[tab] search -- search for a keyword in charts @@ -337,7 +338,7 @@ $ helm s[tab] search (search for a keyword in charts) show (show information of a chart) status (displays the status of the named release) ``` -Cobra allows you to add annotations to your own completions. Simply add the annotation text after each completion, following a `\t` separator. This technique applies to completions returned by `ValidArgs`, `ValidArgsFunction` and `RegisterFlagCompletionFunc()`. For example: +Cobra allows you to add descriptions to your own completions. Simply add the description text after each completion, following a `\t` separator. This technique applies to completions returned by `ValidArgs`, `ValidArgsFunction` and `RegisterFlagCompletionFunc()`. For example: ```go ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) { return []string{"harbor\tAn image registry", "thanos\tLong-term metrics"}, cobra.ShellCompDirectiveNoFileComp