GitHub CLI 如何用 gh completion 为 bash、zsh、fish 和 PowerShell 配置补全？

本文解决一个具体任务：让 GitHub CLI（gh）在你日常使用的 shell 里支持 Tab 补全。gh completion 子命令会按目标 shell 生成对应的补全脚本，支持 bash、zsh、fish 和 PowerShell 四种，用法为 gh completion -s <shell>。该命令不需要 gh auth login 认证，也不会产生遥测事件（见 遥测验收测试），所以可以在任何环境下执行。完成配置后，需要在重启 shell 之后再验证补全是否生效。

先检查：包管理器安装可能已自带补全

gh completion 的官方帮助说明：通过包管理器安装 GitHub CLI 时，很可能不需要额外的 shell 配置即可获得补全支持（帮助中特别提到 Homebrew 场景）。如果你的安装方式是 Homebrew 等包管理器，可以先重启 shell 直接测试补全；只有测试不生效时，再按下面各 shell 的手动配置步骤操作。

另外注意：官方帮助明确提示，配置文件的确切位置可能因系统而异，下文给出的路径以命令帮助文本为准。

按 shell 生成并接入补全脚本

bash：eval 动态加载

bash 的前置依赖是先用你的包管理器安装 bash-completion（命令帮助明确要求）。之后把下面一行加入 ~/.bash_profile：

eval "$(gh completion -s bash)"

这行会在每次 shell 启动时现场生成并加载 bash 补全，不落地任何补全脚本文件。

zsh：生成 _gh 脚本放入 $fpath

zsh 采用“先生成脚本文件、再由 compinit 加载”的方式：

gh completion -s zsh > /usr/local/share/zsh/site-functions/_gh

这条命令会向 /usr/local/share/zsh/site-functions/ 写入 _gh 文件（若该目录无写权限，需要相应权限），把脚本放在 $fpath 路径内的任一位置即可。然后确保 ~/.zshrc 中有以下内容：

autoload -U compinit
compinit -i

命令帮助建议 zsh 版本为 5.7 或更高。

fish：生成 gh.fish 放入 completions 目录

gh completion -s fish > ~/.config/fish/completions/gh.fish

这条命令会在 ~/.config/fish/completions/ 下创建 gh.fish 补全脚本，fish 启动时会自动加载该目录下的补全定义。

PowerShell：写入 profile 脚本

PowerShell 的配置落在 $profile 指向的 profile 脚本里。按帮助文本操作：

mkdir -Path (Split-Path -Parent $profile) -ErrorAction SilentlyContinue
notepad $profile

第一条命令在 profile 目录不存在时创建它（SilentlyContinue 表示已存在时不报错），第二条用记事本打开 profile 文件。然后在文件中加入下面一行并保存：

Invoke-Expression -Command $(gh completion -s powershell | Out-String)

如何验证配置生效

验证分两步：

1. 脚本层面：直接运行 gh completion -s <shell>，输出应为对应 shell 的补全脚本。仓库单元测试 completion_test.go 就是用各脚本的起始行做断言的，可参照核对：bash 输出包含 complete -o default -F __start_gh gh，zsh 输出以 #compdef gh 开头，fish 输出包含 complete -c gh，PowerShell 输出包含 Register-ArgumentCompleter。
2. shell 层面：官方帮助明确要求，测试补全前先重启 shell，然后在 gh 后按 Tab 观察命令/子命令补全是否出现。

参数行为与常见报错

-s, --shell 是唯一参数，合法取值只有 bash、zsh、fish、powershell 四个。两种典型报错及对应处理：

• 传入不支持的 shell，例如 -s csh，会报： invalid argument "csh" for "-s, --shell" flag: valid values are {bash|zsh|fish|powershell} （报错文本见 completion_test.go 中的断言）。
• 在交互式终端中不传 --shell，会报 error: the value for --shell is required；而在非交互（如重定向）环境下不传该参数时，命令默认按 bash 生成脚本（见 completion.go 中的分支逻辑）。

如果配置完成后 Tab 仍无补全，按文档给出的两个方向排查：确认对应 shell 的配置文件（~/.bash_profile、~/.zshrc 等）里已写入上文对应内容，且 zsh 场景下 compinit 已启用；然后确认 shell 已重启。配置文件位置因系统而异这一点，官方帮助也作了提示，遇到路径不存在时以本机实际 shell 配置目录为准。