简体中文 | English | Powershell Gallery | Github | Gitee

Star ⭐️ or Donate 💰 if you like it!

A completion manager for a better and simpler tab-completion experience in PowerShell.

• Built-in completion library.
• More powerful completion menu.
• Sort completion items dynamically based on command history.
• Support multiple languages: en-US, zh-CN, etc.
• Work with other tools.
  • argc-completions
  • Carapace
  • PSFzf

See the Changelog for details.

See the FAQ.

See the Contribution Guide for details.

1. Install the module.

   • Install-Module

     Install-Module PSCompletions -Scope CurrentUser

   • Install-PSResource

     Install-PSResource PSCompletions -Scope CurrentUser

   • Scoop

     • Add the abyss bucket via Github or Gitee.

     • Install it.

       scoop install abyss/abgox.PSCompletions

2. Import the module.

   Import-Module PSCompletions

• Take git as an example.

  1. Add completion: psc add git
  2. Then you can enter git, press Space and Tab key to get command completion.

• Use PSCompletions as a better completion menu without psc add.

  • If there is an official completion for xxx, a similar command may be run:

    xxx completion powershell | Out-String | Invoke-Expression

  • Work with other completion libraries.

    • argc-completions
    • Carapace

  • For more details, please refer to About menu enhance.

• Use PSFzf as the completion menu, refer to Work with PSFzf.

• In addition to the built-in completion menu of PowerShell, PSCompletions module also provides a more powerful completion menu.

  • Setting: psc menu config enable_menu 1 (Default: 1)
  • You can run psc to view the related key bindings.

• It is only available in Windows, because PowerShell in Linux/MacOS does not implement the relevant methods.

• All configurations of it, you can trigger completion by running psc menu, then learn about them by the completion tip.

  • For configured values, 1 means true and 0 means false. (It applies to all configurations of PSCompletions)
  • Some common menu behaviors:
    • Auto-apply when there's only one completion item: psc menu config enable_enter_when_single 1
    • ...

• Setting: psc menu config enable_menu_enhance 1 (Default: 1)

• Now, PSCompletions has two completion implementations.

  • Set-PSReadLineKeyHandler
    • It's used by default.
      • Requires: enable_menu and enable_menu_enhance both set to 1.
      • It will use Set-PSReadLineKeyHandler -Key $PSCompletions.config.trigger_key -ScriptBlock { ... }.
      • The default trigger_key is Tab.
      • So, you cannot use Set-PSReadLineKeyHandler -Key Tab -ScriptBlock { ... }.
    • It use TabExpansion2 to manage completions globally, not limited to those added by psc add.
      • Path completion such as cd/.\/..\/~\/...
      • Build-in commands such as Get-*/Set-*/New-*/...
      • Completion registered by Register-ArgumentCompleter
      • Completion registered by cli or module.
      • ...
  • Register-ArgumentCompleter
    • You can use it by running psc menu config enable_menu_enhance 0.
    • It only works for completions added by psc add.

• Optional Completions: some command completions that like -*, such as --global in git config --global.
• You should use option completion first.
• Taking git as an example, if you want to enter git config user.name --global xxx, you should use --global completion first, and then use user.name, and then enter the name xxx.
• For options ending with =, if there's completion definition, you can directly press the Tab key to get the completions.

• Take git for example, when entering git add, pressing the Space and Tab keys, path completion will not be triggered, only completion provided by the module will be triggered.
• If you want to trigger path completion, you need to enter a content which matches ^(?:\.\.?|~)?(?:[/\\]).*.
• e.g.
  • Enter ./ or .\ and press Tab key to get path completion for the subdirectory or file.
  • Enter ../ or ..\ and press Tab key to get path completion for the parent directory or file.
  • Enter / or \ and press Tab key to get path completion for the sibling directory.
  • More examples: ~/ / ../../ ...
• So you can enter git add ./ and then press Tab key to get the path completion.

• Special symbols after the completion item are used to let you know in advance if completions are available before you press the Tab key.

  • They only exist in completions added by psc add.
  • They can be customized by running psc menu symbol <type> <symbol>
  • For example, you can replace them with empty strings to hide them.
    • psc menu symbol SpaceTab ""
    • psc menu symbol OptionTab ""
    • psc menu symbol WriteSpaceTab ""

• ~,?,! : If there are multiple, you can choose the effect of one of them.

  • ~ : It means that after you apply it, you can press Tab key to continue to get completions.
  • ? : It means that after you apply the option completion, you can press Tab key to continue to get current list of completion items.
  • ! : It means that after you apply the option completion, you should enter a string, then press Tab key to continue to get current list of completion items.
    • If the string has spaces, please use " or ' to wrap it. e.g. "test content"
    • If there's also ~, it means that there's some preset completions, you can press Tab key to continue to get them without entering a string.

• The completion tip is only a helper and can be used as needed.

  • Disable it for all completions: psc menu config enable_tip 0
  • Disable it for a specific completion: psc completion git enable_tip 0

• General structure of the completion tip: Usage + Description + Example

  U: install, add [-g, -u] [options] <app>
  This is a description of the command.
  E: install xxx
     add -g xxx

• Example Analysis:

  1. Usage: Begin with U:
     • command name: install
     • command alias: add
     • required parameters: <app>
       • app is a simple summary of the parameters.
     • optional parameters: -g -u
       • [options]: Some options.
  2. Description: The description of the command.
  3. Example: Begin with E:

• Global language: Default to the language of current system.
  • You can show it by running psc config language.
  • You can change it by running psc config language zh-CN.
• Completion language: The language set for the specified completion.
  • e.g. psc completion git language en-US.
• Available language: In the completion config.json file, there is a language attribute whose value is a list of available languages.

1. If there is Completion language,use it. If not, use Global language.
2. Determine the final language:
   • Determine whether the value of the first step exists in Available language.
   • If it exists, use it.
   • If not, use the first of the Available language. (It's usually en-US)

• PSCompletions depends on PSReadLine, which is a built-in module in PowerShell.
• The completion menu is inspired by PS-GuiCompletion.

• English
• 简体中文