PSCompletions

✨PSCompletions(psc)✨

喜欢这个项目？请给它一个 ⭐️ 或赞赏 💰

介绍

[!Tip]

PowerShell(pwsh): 跨平台的 PowerShell。运行 pwsh/pwsh.exe 启动

Windows PowerShell: Windows 系统内置的 PowerShell。运行 powershell/powershell.exe 启动

它们都可以使用 PSCompletions, 但是更推荐 PowerShell(pwsh)

一个 PowerShell 补全管理模块，更好、更简单、更方便的使用和管理补全
集中管理补全
en-US,zh-CN,… 多语言切换
动态排序补全项(根据使用频次)
更强大的补全菜单
与 argc-completions 结合使用

Demo

[!Tip]

如果这里无法正常显示，可前往官网查看

点击查看 Bilibili 中的介绍及教学视频

demo

新的变化

请查阅更新日志

常见问题

请查阅常见问题

安装

[!Warning]

PowerShell(pwsh): 除非你确定始终会使用管理员权限，否则不要添加 -Scope AllUsers

Windows PowerShell: 除非你确定始终会使用管理员权限，否则不要省略 -Scope CurrentUser

打开 PowerShell

安装模块:

普通安装
```
Install-Module PSCompletions
```

静默安装:

Install-Module PSCompletions -Repository PSGallery -Force

使用 Scoop 安装
- 添加 abyss bucket (Github 或 Gitee)
- 安装它
```
scoop install abyss/abgox.PSCompletions
```

导入模块:
```
Import-Module PSCompletions
```
- 如果不想每次启动 PowerShell 都需要导入 PSCompletions 模块，你可以使用以下命令将导入语句写入 $PROFILE 中
```
echo "Import-Module PSCompletions" >> $PROFILE
```
- 推荐将 Import-Module PSCompletions 添加到 $PROFILE 中靠前的位置，避免出现编码问题
- 关于补全触发按键

卸载

打开 PowerShell
卸载模块:
```
Uninstall-Module PSCompletions
```

使用

[!Tip]

可用补全列表

如果补全列表里没有你想要的补全，你可以提交 issues

也可以与 argc-completions 结合使用

以 git 补全为例

psc add git
然后你就可以输入 git, 按下 Space(空格键) Tab 键来获得命令补全
关于 psc 的更多命令用法，你只需要输入 psc 然后按下 Space(空格键) Tab 键触发补全，通过补全提示信息来了解

贡献

请查阅 CONTRIBUTING

Tips

关于补全触发按键

模块默认使用 Tab 键作为补全菜单触发按键
你可以使用 psc menu config trigger_key <key> 去设置它

[!Warning]
如果需要指定 Set-PSReadLineKeyHandler -Key <key> -Function <MenuComplete|Complete>

请放在 Import-Module PSCompletions 之前
例如:
Set-PSReadLineKeyHandler -Key Tab -Function MenuComplete

Import-Module PSCompletions

关于补全更新

当打开 PowerShell 并导入 PSCompletions 模块后，PSCompletions 会开启一个后台作业去检查远程仓库中补全的状态
获取到更新后，会在下一次打开 PowerShell 并导入 PSCompletions 后显示补全更新提示

关于选项类补全

选项类补全，指的是像 -* 的命令补全，例如 git config --global 中的 --global
你应该优先使用选项类补全
以 git 补全为例，如果你想要输入 git config user.name --global xxx
你应该先补全 --global，然后再补全 user.name，最后输入名称 xxx
对于以 = 结尾的选项，如果有相关补全定义，则可以直接按下 Tab 键触发补全

关于补全菜单

除了 PowerShell 内置的补全菜单，PSCompletions 模块还提供了一个更强大的补全菜单。
- 配置: psc menu config enable_menu 1 (默认开启)
模块提供的补全菜单可用的 Windows 环境：
- PowerShell
- Windows PowerShell
  - 由于 Windows PowerShell 渲染问题，补全菜单的边框样式无法自定义
  - 如果需要自定义，请使用 PowerShell

模块提供的补全菜单中的按键

选用当前选中的补全项: Enter(回车) / Space(空格)
- 当只有一个补全项时，也可以使用 Tab
删除过滤字符: Backspace(退格)
退出补全菜单: Esc / Ctrl + c
- 当过滤区域没有字符时，也可以使用 Backspace(退格) 退出补全菜单

选择补全项:

选择上一项	选择下一项
`Up`	`Down`
`Left`	`Right`
`Shift + Tab`	`Tab`
`Ctrl + u`	`Ctrl + d`
`Ctrl + p`	`Ctrl + n`

补全菜单的所有配置, 你可以输入 psc menu 然后按下 Space(空格键) Tab 键触发补全，通过补全提示信息来了解
- 对于配置的值，1 表示 true，0 表示 false (这适用于 PSCompletions 的所有配置)

关于菜单增强

配置: psc menu config enable_menu_enhance 1 (默认开启)
PSCompletions 对于补全有两种实现
- Set-PSReadLineKeyHandler
  - 默认使用此实现
    - 前提: 配置项 enable_menu 和 enable_menu_enhance 同时为 1
  - 它不再需要循环为所有补全命令注册 Register-ArgumentCompleter，理论上加载速度会更快
  - 它使用 TabExpansion2 全局管理补全，不局限于 psc add 添加的补全
    - 例如:
      - 路径补全: cd/.\/..\/~\/…
      - 内置命令补全: Get-*/Set-*/New-*/…
      - 通过 Register-ArgumentCompleter 注册的补全
      - 与 argc-completions 结合使用
      - 由 cli 或模块注册的补全
      - …
- Register-ArgumentCompleter
  - 可以通过配置 psc menu config enable_menu_enhance 0 来使用它
  - PSCompletions 只对通过 psc add 添加的补全生效
  - 其他补全由 Set-PSReadLineKeyHandler -Key <key> -Function <MenuComplete|Complete> 控制

关于特殊符号

[!Tip]

由于未来的 Windows Terminal 的变化，将导致在补全菜单中无法正常显示 😄🤔😎，因此这三个默认特殊符号将改变。

相关的 issue: https://github.com/microsoft/terminal/issues/18242

变化如下:

😄 => ~

🤔 => ?

😎 => !

补全项后面的特殊符号用于在按下 Tab 键之前提前感知是否有可用的补全项
- 只有通过 psc add 添加的补全中才存在
- 你可以将它们替换成空字符串来隐藏它们
  - psc menu symbol SpaceTab ""
  - psc menu symbol OptionTab ""
  - psc menu symbol WriteSpaceTab ""
~,?,! : 如果出现多个, 表示符合多个条件, 可以选择其中一个效果
- 定义:
  - Normal Completions: 子命令，例如在 git 中的 add/pull/push/commit/…
  - Optional Completions: 可选参数，例如在 git add 中的 -g/-u/…
  - General Optional Completions: 可以用在任何地方的通用可选参数，例如在 git 中的 --help/…
  - Current Completions: 当前的补全项列表
- ~ : 表示选用当前选中的补全后, 可以按下 Space(空格键) 和 Tab 键继续获取补全
  - 可通过 psc menu symbol SpaceTab <symbol> 自定义此符号
- ? : 表示选用当前选中的补全(Optional Completions 或 General Optional Completions)后, 可以按下 Space(空格键) 和 Tab 键继续获取 Current Completions
  - 可通过 psc menu symbol OptionTab <symbol> 自定义此符号
- ! : 表示选用当前选中的补全(Optional Completions 或 General Optional Completions)后, 你可以按下 Space(空格键), 再输入一个字符串, 然后按下 Space(空格键) 和 Tab 键继续获取补全
  - 如果字符串有空格, 请使用 "(引号) 或 '(单引号) 包裹，如 "test content"
  - 如果同时还有 ~, 表示有预设的补全项, 你可以不输入字符串, 直接按下 Space(空格键) 和 Tab 键继续获取它们
  - 可通过 psc menu symbol WriteSpaceTab <symbol> 自定义此符号
- 所有补全都可以在输入部分字符后按下 Tab 键触发补全

关于补全提示信息

补全提示信息只是辅助, 你也可以使用 psc menu config enable_tip 0 来禁用补全提示信息
- 启用补全提示信息: psc menu config enable_tip 1
- 也可以禁用特定补全的提示信息，如 psc
  - psc completion psc enable_tip 0

补全提示信息一般由三部分组成: 用法(Usage) + 描述(Description) + 举例(Example)

U: install|add [-g|-u] [options] <app>
这里是命令的描述说明
(在 U: 和 E: 之间的内容都是命令描述)
E: install xxx
   add -g xxx

示例解析:
1. 用法: 以 U: 开头(Usage)
  - 命令名称: install
  - 命令别名: add
  - 必填参数: <app>
    - app 是对必填参数的简要概括
  - 可选参数: -g -u
  - [options] 表示泛指一些选项类参数
2. 描述: 在 U: 和 E: 之间的内容
3. 举例: 以 E: 开头(Example)

关于语言

Global language: 默认为当前的系统语言
- psc config language 可以查看全局的语言配置
- psc config language zh-CN 可以更改全局的语言配置
Completion language: 为指定的补全设置的语言
- 例如: psc completion git language en-US
Available language: 每一个补全的 config.json 文件中有一个 language 属性，它的值是一个可用的语言列表

确定语言

确定指定的语言: 如果有 Completion language，优先使用它，没有则使用 Global language
确定最终使用的语言:
- 判断第一步确定的值是否存在于 Available language 中
- 如果存在，则使用它
- 如果不存在，直接使用 Available language 中的第一种语言(一般为 en-US)

关于路径补全

以 git 为例，当输入 git add，此时按下 Space 和 Tab 键，不会触发路径补全，只会触发模块提供的命令补全
如果你希望触发路径补全，你需要输入内容，且内容符合正则 ^(?:\.\.?|~)?(?:[/\\]).*
比如:
- 输入 ./ 或 .\ 后按下 Tab 以获取 子目录 或文件的路径补全
- 输入 ../ 或 ..\ 后按下 Tab 以获取 父级目录 或文件的路径补全
- 输入 / 或 \ 后按下 Tab 以获取 同级目录 的路径补全
- 更多的: ~/ / ../../ …
因此，你应该输入 git add ./ 这样的命令再按下 Tab 键来获取路径补全

致谢

PS-GuiCompletion: 模块的补全菜单受到它的启发

补全列表

说明
- Completion ：可添加的补全。点击跳转命令官方网站，按照数字字母排序(0-9,a-z)。
- Language: 支持的语言，以及完成进度
  - 这个进度是和 config.json 中定义的第一个语言相比，一般是 en-US
- Description: 命令描述

This site is open source. Improve this page.