mirror
/
cobra
mirror of https://github.com/spf13/cobra.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

Copyedit shell-completion related documentation

This commit is contained in:
Anthony Fok 2021-02-09 14:08:42 -07:00
parent b73b344b63
commit 07445ea179
No known key found for this signature in database
GPG Key ID: EA2500B412C59ACF
4 changed files with 38 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -753,7 +753,7 @@ Cobra can generate documentation based on subcommands, flags, etc. Read more abo
## Generating shell completions ## Generating shell completions
Cobra can generate a shell-completion file for the following shells: Bash, Zsh, Fish, Powershell. If you add more information to your commands, these completions can be amazingly powerful and flexible. Read more about it in [Shell Completions](shell_completions.md). Cobra can generate a shell-completion file for the following shells: bash, zsh, fish, PowerShell. If you add more information to your commands, these completions can be amazingly powerful and flexible. Read more about it in [Shell Completions](shell_completions.md).
# License # License

2
bash_completions.md
View File

@ -4,7 +4,7 @@ Please refer to [Shell Completions](shell_completions.md) for details.
## Bash legacy dynamic completions ## Bash legacy dynamic completions
For backwards-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. 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.
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. 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.

2
powershell_completions.go
View File

@ -181,7 +181,7 @@ Register-ArgumentCompleter -CommandName '%[1]s' -ScriptBlock {
# store temporay because switch will overwrite $_ # store temporay because switch will overwrite $_
$comp = $_ $comp = $_
# Powershell supports three different completion modes # PowerShell supports three different completion modes
# - TabCompleteNext (default windows style - on each key press the next option is displayed) # - TabCompleteNext (default windows style - on each key press the next option is displayed)
# - Complete (works like bash) # - Complete (works like bash)
# - MenuComplete (works like zsh) # - MenuComplete (works like zsh)

68
shell_completions.md
View File

@ -4,10 +4,10 @@ Cobra can generate shell completions for multiple shells.
The currently supported shells are: The currently supported shells are:
- Bash - Bash
- Zsh - Zsh
- Fish - fish
- PowerShell - PowerShell
If you are using the generator you can create a completion command by running If you are using the generator, you can create a completion command by running
```bash ```bash
cobra add completion cobra add completion
@ -17,46 +17,46 @@ and then modifying the generated `cmd/completion.go` file to look something like
```go ```go
var completionCmd = &cobra.Command{ var completionCmd = &cobra.Command{
Use: "completion [bash|zsh|fish|powershell]", Use: "completion [bash|zsh|fish|powershell]",
Short: "Generate completion script", Short: "Generate completion script",
Long: `To load completions: Long: `To load completions:
Bash: Bash:
$ source <(yourprogram completion bash) $ source <(yourprogram completion bash)
# To load completions for each session, execute once: # To load completions for each session, execute once:
Linux: # Linux:
$ yourprogram completion bash > /etc/bash_completion.d/yourprogram $ yourprogram completion bash > /etc/bash_completion.d/yourprogram
MacOS: # macOS:
$ yourprogram completion bash > /usr/local/etc/bash_completion.d/yourprogram $ yourprogram completion bash > /usr/local/etc/bash_completion.d/yourprogram
Zsh: Zsh:
# If shell completion is not already enabled in your environment you will need # If shell completion is not already enabled in your environment,
# to enable it. You can execute the following once: # you will need to enable it. You can execute the following once:
$ echo "autoload -U compinit; compinit" >> ~/.zshrc $ echo "autoload -U compinit; compinit" >> ~/.zshrc
# To load completions for each session, execute once: # To load completions for each session, execute once:
$ yourprogram completion zsh > "${fpath[1]}/_yourprogram" $ yourprogram completion zsh > "${fpath[1]}/_yourprogram"
# You will need to start a new shell for this setup to take effect. # You will need to start a new shell for this setup to take effect.
Fish: fish:
$ yourprogram completion fish | source $ yourprogram completion fish | source
# To load completions for each session, execute once: # To load completions for each session, execute once:
$ yourprogram completion fish > ~/.config/fish/completions/yourprogram.fish $ yourprogram completion fish > ~/.config/fish/completions/yourprogram.fish
Powershell: PowerShell:
PS> yourprogram completion powershell | Out-String | Invoke-Expression PS> yourprogram completion powershell | Out-String | Invoke-Expression
# To load completions for every new session, run: # To load completions for every new session, run:
PS> yourprogram completion powershell > yourprogram.ps1 PS> yourprogram completion powershell > yourprogram.ps1
# and source this file from your powershell profile. # and source this file from your PowerShell profile.
`, `,
DisableFlagsInUseLine: true, DisableFlagsInUseLine: true,
ValidArgs: []string{"bash", "zsh", "fish", "powershell"}, ValidArgs: []string{"bash", "zsh", "fish", "powershell"},
@ -76,7 +76,7 @@ PS> yourprogram completion powershell > yourprogram.ps1
} }
``` ```
**Note:** The cobra generator may include messages printed to stdout for example if the config file is loaded, this will break the auto complete script so must be removed. **Note:** The cobra generator may include messages printed to stdout, for example, if the config file is loaded; this will break the auto-completion script so must be removed.
# Customizing completions # Customizing completions
@ -368,12 +368,12 @@ completion firstcommand secondcommand
``` ```
### Bash legacy dynamic completions ### Bash legacy dynamic completions
For backwards-compatibility, Cobra still supports its bash legacy dynamic completion solution. For backward compatibility, Cobra still supports its bash legacy dynamic completion solution.
Please refer to [Bash Completions](bash_completions.md) for details. Please refer to [Bash Completions](bash_completions.md) for details.
## Zsh completions ## Zsh completions
Cobra supports native Zsh completion generated from the root `cobra.Command`. Cobra supports native zsh completion generated from the root `cobra.Command`.
The generated completion script should be put somewhere in your `$fpath` and be named The generated completion script should be put somewhere in your `$fpath` and be named
`_<yourProgram>`. You will need to start a new shell for the completions to become available. `_<yourProgram>`. You will need to start a new shell for the completions to become available.
@ -392,7 +392,7 @@ status -- displays the status of the named release
$ helm s[tab] $ helm s[tab]
search show status search show status
``` ```
*Note*: Because of backwards-compatibility requirements, we were forced to have a different API to disable completion descriptions between `Zsh` and `Fish`. *Note*: Because of backward-compatibility requirements, we were forced to have a different API to disable completion descriptions between `zsh` and `fish`.
### Limitations ### Limitations
@ -403,12 +403,12 @@ search show status
### Zsh completions standardization ### Zsh completions standardization
Cobra 1.1 standardized its zsh completion support to align it with its other shell completions. Although the API was kept backwards-compatible, some small changes in behavior were introduced. Cobra 1.1 standardized its zsh completion support to align it with its other shell completions. Although the API was kept backward-compatible, some small changes in behavior were introduced.
Please refer to [Zsh Completions](zsh_completions.md) for details. Please refer to [Zsh Completions](zsh_completions.md) for details.
## Fish completions ## fish completions
Cobra supports native Fish completions generated from the root `cobra.Command`. You can use the `command.GenFishCompletion()` or `command.GenFishCompletionFile()` functions. You must provide these functions with a parameter indicating if the completions should be annotated with a description; Cobra will provide the description automatically based on usage information. You can choose to make this option configurable by your users. Cobra supports native fish completions generated from the root `cobra.Command`. You can use the `command.GenFishCompletion()` or `command.GenFishCompletionFile()` functions. You must provide these functions with a parameter indicating if the completions should be annotated with a description; Cobra will provide the description automatically based on usage information. You can choose to make this option configurable by your users.
``` ```
# With descriptions # With descriptions
$ helm s[tab] $ helm s[tab]
@ -418,11 +418,11 @@ search (search for a keyword in charts) show (show information of a chart) s
$ helm s[tab] $ helm s[tab]
search show status search show status
``` ```
*Note*: Because of backwards-compatibility requirements, we were forced to have a different API to disable completion descriptions between `Zsh` and `Fish`. *Note*: Because of backward-compatibility requirements, we were forced to have a different API to disable completion descriptions between `zsh` and `fish`.
### Limitations ### Limitations
* Custom completions implemented in Bash scripting (legacy) are not supported and will be ignored for `fish` (including the use of the `BashCompCustom` flag annotation). * Custom completions implemented in bash scripting (legacy) are not supported and will be ignored for `fish` (including the use of the `BashCompCustom` flag annotation).
* You should instead use `ValidArgsFunction` and `RegisterFlagCompletionFunc()` which are portable to the different shells (`bash`, `zsh`, `fish`, `powershell`). * You should instead use `ValidArgsFunction` and `RegisterFlagCompletionFunc()` which are portable to the different shells (`bash`, `zsh`, `fish`, `powershell`).
* The function `MarkFlagCustom()` is not supported and will be ignored for `fish`. * The function `MarkFlagCustom()` is not supported and will be ignored for `fish`.
* You should instead use `RegisterFlagCompletionFunc()`. * You should instead use `RegisterFlagCompletionFunc()`.
@ -440,7 +440,7 @@ search show status
Cobra supports native PowerShell completions generated from the root `cobra.Command`. You can use the `command.GenPowerShellCompletion()` or `command.GenPowerShellCompletionFile()` functions. To include descriptions use `command.GenPowerShellCompletionWithDesc()` and `command.GenPowerShellCompletionFileWithDesc()`. Cobra will provide the description automatically based on usage information. You can choose to make this option configurable by your users. Cobra supports native PowerShell completions generated from the root `cobra.Command`. You can use the `command.GenPowerShellCompletion()` or `command.GenPowerShellCompletionFile()` functions. To include descriptions use `command.GenPowerShellCompletionWithDesc()` and `command.GenPowerShellCompletionFileWithDesc()`. Cobra will provide the description automatically based on usage information. You can choose to make this option configurable by your users.
The script is designed to support all three Powershell completion modes: The script is designed to support all three PowerShell completion modes:
* TabCompleteNext (default windows style - on each key press the next option is displayed) * TabCompleteNext (default windows style - on each key press the next option is displayed)
* Complete (works like bash) * Complete (works like bash)
@ -468,7 +468,7 @@ search show status
### Limitations ### Limitations
* Custom completions implemented in Bash scripting (legacy) are not supported and will be ignored for `powershell` (including the use of the `BashCompCustom` flag annotation). * Custom completions implemented in bash scripting (legacy) are not supported and will be ignored for `powershell` (including the use of the `BashCompCustom` flag annotation).
* You should instead use `ValidArgsFunction` and `RegisterFlagCompletionFunc()` which are portable to the different shells (`bash`, `zsh`, `fish`, `powershell`). * You should instead use `ValidArgsFunction` and `RegisterFlagCompletionFunc()` which are portable to the different shells (`bash`, `zsh`, `fish`, `powershell`).
* The function `MarkFlagCustom()` is not supported and will be ignored for `powershell`. * The function `MarkFlagCustom()` is not supported and will be ignored for `powershell`.
* You should instead use `RegisterFlagCompletionFunc()`. * You should instead use `RegisterFlagCompletionFunc()`.