PSCompletions

✨PSCompletions(psc)✨

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

---

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

介绍

[!Tip]

• PowerShell(pwsh): 跨平台的 PowerShell (Core)，运行 pwsh/pwsh.exe 启动
• Windows PowerShell: Windows 系统内置的 PowerShell (Desktop)，运行 powershell/powershell.exe 启动
• 它们都可以使用 PSCompletions，但是更推荐 PowerShell(pwsh)

一个补全管理器，为 PowerShell 带来更出色、更简便的 Tab 补全体验。

• 内置的补全库
• 更强大的补全菜单
• 根据命令历史动态排序补全项
• 支持多种语言: en-US, zh-CN 等
• 与其他工具协作
  • argc-completions
  • Carapace
  • PSFzf

演示

[!Tip]

• 如果这里无法显示，可前往官网查看
• 点击查看 Bilibili 中的介绍及教学视频

新的变化

请查阅 更新日志

常见问题

请查阅 常见问题

贡献

请查阅 贡献指南

安装

1. 安装模块

   • Install-Module

     Install-Module PSCompletions -Scope CurrentUser
     

   • Install-PSResource

     Install-PSResource PSCompletions -Scope CurrentUser
     

   • Scoop

     • 添加 abyss bucket (Github 或 Gitee)

     • 安装它

       scoop install abyss/abgox.PSCompletions
       

2. 导入模块

   Import-Module PSCompletions
   

使用

• 以 git 补全为例

  1. 使用 psc add git 添加补全
  2. 输入 git，按下 Space(空格键) 和 Tab 键获取命令补全

• 不使用 PSCompletions 的补全库，只将它作为一个更好的补全菜单

  • 如果存在官方补全，可运行类似的命令

    xxx completion powershell | Out-String | Invoke-Expression
    

  • 使用其他的补全库

    • argc-completions
    • Carapace

  • 更多详情，参考 菜单增强

• 使用 PSFzf 作为补全菜单，参考 与 PSFzf 结合使用

Tips

关于补全菜单

• 除了 PowerShell 内置的补全菜单，PSCompletions 模块还提供了一个更强大的补全菜单。

  • 配置: psc menu config enable_menu 1 (默认开启)
  • 相关的按键绑定可运行 psc 查看

• 它只在 Windows 中可用，因为在 Linux/MacOS 中 PowerShell 没有实现相关底层方法

• 补全菜单的所有配置，你可以输入 psc menu 然后按下 Space(空格键) 和 Tab 键触发补全，通过 补全提示信息 来了解

  • 对于配置的值，1 表示 true，0 表示 false (这适用于 PSCompletions 的所有配置)
  • 一些常见的菜单行为:
    • 只有一个补全项时自动应用: psc menu config enable_enter_when_single 1
    • …

关于菜单增强

• 配置: psc menu config enable_menu_enhance 1 (默认开启)

• PSCompletions 对于补全有两种实现

  • Set-PSReadLineKeyHandler

    • 默认使用此实现
      • 前提: 配置项 enable_menu 和 enable_menu_enhance 同时为 1
      • 它会使用 Set-PSReadLineKeyHandler -Key $PSCompletions.config.trigger_key -ScriptBlock { ... }
      • 而默认的 trigger_key 是 Tab
      • 因此，你不能再使用 Set-PSReadLineKeyHandler -Key Tab -ScriptBlock { ... }
    • 它使用 TabExpansion2 全局管理补全，不局限于 psc add 添加的补全
      • 路径补全: cd/.\/..\/~\/…
      • 内置命令补全: Get-*/Set-*/New-*/…
      • 通过 Register-ArgumentCompleter 注册的补全
      • 由 cli 或模块注册的补全
      • …

  • Register-ArgumentCompleter

    • 可以通过运行 psc menu config enable_menu_enhance 0 来使用它
    • 则模块的补全菜单只对通过 psc add 添加的补全生效

关于选项类补全

• 选项类补全，指的是像 -* 的命令补全，例如 git config --global 中的 --global
• 你应该优先使用选项类补全
• 以 git 补全为例，如果你想要输入 git config user.name --global xxx
• 你应该先补全 --global，然后再补全 user.name，最后输入名称 xxx

关于路径补全

• 以 git 为例，当输入 git add，此时按下 Space(空格键) 和 Tab 键，不会触发路径补全，只会触发模块提供的命令补全
• 如果你希望触发路径补全，你需要输入内容，且内容符合正则 ^(?:\.\.?|~)?(?:[/\\]).*

• 比如:

  • 输入 ./ 或 .\ 后按下 Tab 以获取 子目录 或 文件 的路径补全
  • 输入 ../ 或 ..\ 后按下 Tab 以获取 父级目录 或 文件 的路径补全
  • 输入 / 或 \ 后按下 Tab 以获取 同级目录 的路径补全
  • 更多的: ~/ / ../../ …
• 因此，你应该输入 git add ./ 这样的命令再按下 Tab 键来获取路径补全

关于特殊符号

[!Tip]

• 由于 Windows Terminal 的变更导致在补全菜单中无法正常显示 😄🤔😎，因此将更换它们。
• 相关的 issue: https://github.com/microsoft/terminal/issues/18242
• 更改为: ~,?,!

• 补全项后面的特殊符号用于在按下 Tab 键之前提前感知是否有可用的补全项

  • 只有通过 psc add 添加的补全中才存在
  • 你可以使用 psc menu symbol <type> <symbol> 来自定义
  • 例如，你可以替换成空字符串来隐藏它们
    • psc menu symbol SpaceTab ""
    • psc menu symbol OptionTab ""
    • psc menu symbol WriteSpaceTab ""

• ~,?,! : 如果出现多个，表示符合多个条件

  • ~ : 表示选用当前选中的补全后，可以按下 Tab 键继续获取补全
  • ? : 表示选用当前选中的 选项类补全 后，可以按下 Tab 键继续获取当前的补全项列表

  • ! : 表示选用当前选中的 选项类补全 后，你应该输入一个字符串，然后按下 Tab 键继续获取当前的补全项列表

    • 如果字符串有空格，请使用 " 或 ' 包裹，如 "test content"
    • 如果同时还有 ~，表示有预设的补全项，你可以不输入字符串，直接按下 Tab 键继续获取它们

关于补全提示信息

• 补全提示信息只是辅助，可按需使用

  • 禁用所有补全的提示信息: psc menu config enable_tip 0
  • 禁用特定补全的提示信息: psc completion git 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 属性，它的值是一个可用的语言列表

确定语言

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

致谢

• PSCompletions 依赖于 PSReadLine，它是 PowerShell 的一个内置模块
• 而它的 补全菜单 则来自于 PS-GuiCompletion 的启发

补全列表

• 简体中文
• English

This site is open source. Improve this page.