PSCompletions

✨PSCompletions(psc)✨

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

socialify

Star ⭐️ or Donate 💰 if you like it!

Introduce

[!Tip]

PowerShell(pwsh): A cross-platform PowerShell (Core). Start it by running pwsh/pwsh.exe.

Windows PowerShell: A PowerShell (Desktop) which is built-in on Windows system. Start it by running powershell/powershell.exe.

They can both use PSCompletions, but PowerShell(pwsh) is more recommended.

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

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

Demo

[!Tip]

If it cannot be displayed here, you can check it on the official website.

Click to view the videos on Bilibili.

demo

What’s new

See the Changelog for details.

FAQ

See the FAQ.

Contribution

See the Contribution Guide for details.

How to install

Install the module.

Install-Module
```
Install-Module PSCompletions
```
Install-PSResource
```
Install-PSResource PSCompletions
```
Scoop
- Add the abyss bucket via Github or Gitee.
- Install it.
```
scoop install abyss/abgox.PSCompletions
```

Import the module.
```
Import-Module PSCompletions
```

[!Tip]

If you use . $Profile, please run psc to reload the module’s key bindings and data.

Refer to: https://pscompletions.abgox.com/faq/source-profile

How to use

Use the built-in completion library, like git.
1. Add completion: psc add git
2. Then you can enter git, press Space and Tab key to get command completion.
Use official completion or other completion libraries.
- 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.

Tips

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 uses Set-PSReadLineKeyHandler -Key <Key> -ScriptBlock { ... }.
      - <Key> is the value of psc menu config trigger_key (default: 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.

About option completion

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.

About path completion

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.

About special symbols

[!Tip]

Due to changes in Windows Terminal, 😄🤔😎 cannot be displayed properly in the completion menu, so they will be replaced.

Related issue: https://github.com/microsoft/terminal/issues/18242

New symbols: ~,?,!

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.

About completion tip

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:

About language

[!Tip]

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.

If there is Completion language,use it. If not, use Global 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: en-US

Acknowledgements

PSReadLine: A built-in module in PowerShell, which is used to enhance command line editing experience.
- PSCompletions uses Set-PSReadLineKeyHandler and Get-PSReadLineOption.
PS-GuiCompletion: GUI-style tab-completion menu for PowerShell.
- The completion menu of PSCompletions is inspired by it.

Available Completions

This site is open source. Improve this page.