Skip to content

Latest commit

 

History

History
412 lines (329 loc) · 31.8 KB

README-CN.md

File metadata and controls

412 lines (329 loc) · 31.8 KB

✨PSCompletions(psc)✨

English | 简体中文 | Github | Gitee

license module version PowerShell Gallery code size repo size created

介绍

Tip

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

如果 PSCompletions 对你有所帮助，请考虑给它一个 Star ⭐

新的变化

常见问题

安装

  1. 打开 PowerShell

  2. 安装模块:

    • 除非你确定始终会使用管理员权限打开 PowerShell，否则不要省略 -Scope CurrentUser
    Install-Module PSCompletions -Scope CurrentUser
    • 静默安装:
    Install-Module PSCompletions -Scope CurrentUser -Repository PSGallery -Force

  3. 导入模块:

    Import-Module PSCompletions
    • 如果不想每次启动 PowerShell 都需要导入 PSCompletions 模块，你可以使用以下命令将导入语句写入 $PROFILE 中
    echo "Import-Module PSCompletions" >> $PROFILE

Warning

  • 导入 PSCompletions 后，就不要使用 Set-PSReadLineKeyHandler -Key <key> -Function MenuComplete 了
  • 因为 PSCompletions 使用了它，如果再次使用，会覆盖 PSCompletions 中的设置，导致 PSCompletions 补全菜单无法正常工作
  • 你应该通过 PSCompletions 中的配置去设置它
  • 详细配置请参考 关于补全触发按键
+ Import-Module PSCompletions

- Set-PSReadLineKeyHandler -Key <key> -Function MenuComplete

卸载

  1. 打开 PowerShell
  2. 卸载模块: 
    Uninstall-Module PSCompletions

使用

Tip

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

Demo

demo

贡献

Tips

关于补全触发按键

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

Warning

  • 导入 PSCompletions 后，就不要使用 Set-PSReadLineKeyHandler -Key <key> -Function MenuComplete 了
  • 因为 PSCompletions 使用了它，如果再次使用，会覆盖 PSCompletions 中的设置，导致 PSCompletions 补全菜单无法正常工作
+ Import-Module PSCompletions

- Set-PSReadLineKeyHandler -Key <key> -Function MenuComplete

关于补全更新

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

关于选项类补全

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

关于补全菜单

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

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

  • 模块提供的补全菜单基于 PS-GuiCompletion 的实现思路，感谢 PS-GuiCompletion !

  • 模块提供的补全菜单可用的 Windows 环境：

    • PowerShell v4.0.0+ support
    • Windows PowerShell v4.1.0+ support
      • 由于 Windows PowerShell 渲染问题，补全菜单的边框样式无法自定义
      • 如果需要自定义，请使用 PowerShell

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

    1. 选用当前选中的补全项: Enter(回车键)

      • 当只有一个补全项时，也可以使用 Tab 或 Space(空格) 键

    2. 删除过滤字符: Backspace(退格键)

    3. 退出补全菜单: ESC / Ctrl + c

      • 当过滤区域没有字符时，也可以使用 Backspace(退格键) 退出补全菜单

    4. 选择补全项:

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

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

    • 对于配置的值，1 表示 true，0 表示 false (这适用于 PSCompletions 的所有配置)

关于菜单增强 v4.2.0+ support

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

  • 现在，PSCompletions 对于补全有两种实现

    1. Register-ArgumentCompleter

      • v4.1.0 support 及之前版本都使用此实现
      • v4.2.0+ support: 此实现变为可选
        • 你可以运行 psc menu config enable_menu_enhance 0 来继续使用它
        • 但并不推荐，它只能用于 psc add 添加的补全

    2. Set-PSReadLineKeyHandler

      • v4.2.0+ support: 默认使用此实现
        • 需要 enable_menu 和 enable_menu_enhance 同时为 1
      • 它不再需要循环为所有补全命令注册 Register-ArgumentCompleter，理论上加载速度会更快
      • 同时使用 TabExpansion2 全局管理补全，不局限于 psc add 添加的补全

关于特殊符号

Tip

  • 由于未来的 Windows Terminal 的变化，将导致在补全菜单中无法正常显示 😄🤔😎，因此这三个默认特殊符号将改变。
  • 相关的 issue: microsoft/terminal#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 键触发补全

    • 对于以 = 结尾的选项，如果有相关补全定义，则可以直接按下 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 属性，它的值是一个可用的语言列表

确定语言

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

关于路径补全

  • 以 git 为例，当输入 git add，此时按下 Space 和 Tab 键，不会触发路径补全，只会触发模块提供的命令补全

  • 如果你希望触发路径补全，你需要输入内容，且内容符合正则 ^(?:\.\.?|~)?(?:[/\\]).*

  • 比如:

    • 输入 ./ 或 .\ 后按下 Tab 以获取 子目录 或 文件 的路径补全
    • 输入 ../ 或 ..\ 后按下 Tab 以获取 父级目录 或 文件 的路径补全
    • 输入 / 或 \ 后按下 Tab 以获取 同级目录 的路径补全
    • 更多的: ~/ / ../../ ...

  • 因此，你应该输入 git add ./ 这样的命令再按下 Tab 键来获取路径补全

Stars

如果 PSCompletions 对你有所帮助，请考虑给它一个 Star ⭐

stargazer-widget

赞赏支持

Buy Me a Coffee at ko-fi.com

赞赏支持

补全列表

  • 说明

    • Completion ：可添加的补全。点击跳转命令官方网站，按照数字字母排序(0-9,a-z)。

      • 特殊情况: abc(a)，这表示你需要通过 psc add abc 去下载它，但默认使用 a 而不是 abc 去触发补全

    • Language: 支持的语言，以及完成进度

      • 这个进度是和 config.json 中定义的第一个语言相比，一般是 en-US

    • Description: 命令描述

Completion Language Description
7z en-US
zh-CN(100%)		 7-Zip 的命令行 cli 程序。
arch en-US
zh-CN(100%)		 显示当前系统架构。
补全基于 uutils/coreutils 编写。
b2sum en-US
zh-CN(13.33%)		 Compute and check message digests.
Completion was written based on uutils/coreutils.
b3sum en-US
zh-CN(13.33%)		 Compute and check message digests.
Completion was written based on uutils/coreutils.
base32 en-US
zh-CN(28.57%)		 Encode/decode data and print to standard output.
Completion was written based on uutils/coreutils.
base64 en-US
zh-CN(28.57%)		 Encode/decode data and print to standard output.
Completion was written based on uutils/coreutils.
basename en-US
zh-CN(28.57%)		 Print NAME with any leading directory components removed.
Completion was written based on uutils/coreutils.
basenc en-US
zh-CN(13.33%)		 Encode/decode data and print to standard output.
Completion was written based on uutils/coreutils.
bun en-US
zh-CN(100%)		 Bun - JavaScript 运行时和工具包。
cargo en-US
zh-CN(100%)		 cargo - Rust 包管理器。
chfs en-US
zh-CN(100%)		 CuteHttpFileServer - 一个免费的、HTTP协议的文件共享服务器。
choco en-US
zh-CN(100%)		 choco(chocolatey) - 软件管理。
cksum en-US
zh-CN(20%)		 Print CRC and size for each file.
Completion was written based on uutils/coreutils.
comm en-US
zh-CN(20%)		 Compare two sorted files line by line.
Completion was written based on uutils/coreutils.
conda en-US
zh-CN(100%)		 conda - 二进制包和环境管理器。
csplit en-US
zh-CN(18.18%)		 Split a file into sections determined by context lines.
Completion was written based on uutils/coreutils.
cut en-US
zh-CN(15.38%)		 Print specified byte or field columns from each line of stdin or the input files.
Completion was written based on uutils/coreutils.
date en-US
zh-CN(14.29%)		 Print or set the system date and time.
Completion was written based on uutils/coreutils.
dd en-US
zh-CN(100%)		 复制并转换文件系统资源。
补全基于 uutils/coreutils 编写。
deno en-US
zh-CN(100%)		 Deno - 安全的 JavaScript 和 TypeScript 运行时。
df en-US
zh-CN(5.71%)		 Show information about the file system on which each FILE resides, or all file systems by default.
Completion was written based on uutils/coreutils.
dircolors en-US
zh-CN(25%)		 Output commands to set the LS_COLORS environment variable.
Completion was written based on uutils/coreutils.
dirname en-US
zh-CN(40%)		 Strip last component from file name.
Completion was written based on uutils/coreutils.
docker en-US
zh-CN(100%)		 docker - 容器应用开发。
du en-US
zh-CN(2.17%)		 Estimate file space usage.
Completion was written based on uutils/coreutils.
env en-US
zh-CN(16.67%)		 Set each NAME to VALUE in the environment and run COMMAND.
Completion was written based on uutils/coreutils.
factor en-US
zh-CN(20%)		 Print the prime factors of the given NUMBER(s).
Completion was written based on uutils/coreutils.
fmt en-US
zh-CN(11.76%)		 Reformat paragraphs from input files (or stdin) to stdout.
Completion was written based on uutils/coreutils.
fnm en-US
zh-CN(8.33%)		 快速、简单的 Node.js 版本管理器，使用 Rust 构建。
fold en-US
zh-CN(28.57%)		 Writes each file (or standard input if no files are given) to standard output whilst breaking long lines.
Completion was written based on uutils/coreutils.
git en-US
zh-CN(99.11%)		 Git - 版本控制系统。
hashsum en-US
zh-CN(6.45%)		 Compute and check message digests.
Completion was written based on uutils/coreutils.
head en-US
zh-CN(22.22%)		 Print the first 10 lines of each 'FILE' to standard output.
Completion was written based on uutils/coreutils.
join en-US
zh-CN(11.11%)		 For each pair of input lines with identical join fields, write a line to standard output.
The default join field is the first, delimited by blanks.
Completion was written based on uutils/coreutils.
kubectl en-US
zh-CN(100%)		 Kubernetes 又称 K8s，是一个开源系统，用于自动化部署、扩展和管理容器化应用程序。
kubectl 是它的命令行工具
link en-US
zh-CN(100%)		 调用 link 函数为现有的 FILE1 创建名为 FILE2 的链接。
补全基于 uutils/coreutils 编写。
ln en-US
zh-CN(11.76%)		 Make links between files.
Completion was written based on uutils/coreutils.
md5sum en-US
zh-CN(14.29%)		 Compute and check message digests.
Completion was written based on uutils/coreutils.
mktemp en-US
zh-CN(20%)		 Create a temporary file or directory.
Completion was written based on uutils/coreutils.
ngrok en-US
zh-CN(100%)		 ngrok - 面向开发人员的统一入口平台。
将 localhost 连接到 Internet 以测试应用程序和 API。
nl en-US
zh-CN(6.67%)		 Number lines of files.
Completion was written based on uutils/coreutils.
npm en-US
zh-CN(100%)		 npm - 软件包管理器。
nproc en-US
zh-CN(33.33%)		 Print the number of cores available to the current process.
Completion was written based on uutils/coreutils.
nrm en-US
zh-CN(100%)		 nrm - npm 镜像源管理。
numfmt en-US
zh-CN(7.69%)		 Convert numbers from/to human-readable strings.
Completion was written based on uutils/coreutils.
nvm en-US
zh-CN(100%)		 nvm - node 版本管理器。
od en-US
zh-CN(4.65%)		 Dump files in octal and other formats.
Completion was written based on uutils/coreutils.
paste en-US
zh-CN(28.57%)		 Write lines consisting of the sequentially corresponding lines from each 'FILE', separated by 'TAB's, to standard output.
Completion was written based on uutils/coreutils.
pdm en-US
zh-CN(0.31%)		 A modern Python package and dependency manager supporting the latest PEP standards.
pip en-US
zh-CN(99.42%)		 pip - Python 包管理器。
pnpm en-US
zh-CN(100%)		 pnpm - 软件包管理器。
powershell en-US
zh-CN(100%)		 Windows PowerShell 命令行 CLI. (powershell.exe)
psc en-US
zh-CN(97.55%)		 PSCompletions 模块的补全提示
它只能更新，不能移除
如果移除它，将会自动重新添加
pwsh en-US
zh-CN(100%)		 PowerShell 命令行 CLI。(pwsh.exe)
python en-US
zh-CN(100%)		 python - 命令行。
scoop en-US
zh-CN(100%)		 Scoop - 软件管理
sfsu en-US
zh-CN(6.67%)		 Scoop utilities that can replace the slowest parts of Scoop, and run anywhere from 30-100 times faster.
volta en-US
zh-CN(100%)		 volta - 无障碍 JavaScript 工具管理器。
winget en-US
zh-CN(100%)		 WinGet - Windows 程序包管理器。
wsh en-US
zh-CN(3.45%)		 wsh is a small utility that lets you do cool things with Wave Terminal, right from the command line.
wsl en-US
zh-CN(100%)		 WSL - 适用于 Linux 的 Windows 子系统。
wt en-US
zh-CN(100%)		 Windows Terminal 命令行终端。
你可以使用此命令启动一个终端。
yarn en-US
zh-CN(100%)		 yarn - 软件包管理器。
... ...                           ...