企业官网建设流程全解析

Sway 项目 forc completions 命令完全指南：为 Bash、Zsh、Fish 与 PowerShell 启用 Tab 补全

【免费下载链接】sway🌴 Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway

forc completions是 Sway 智能合约工具链中用于生成 shell 补全脚本的命令，它把forc（Fuel Orchestrator）全部子命令与参数转化为 Bash、Zsh、Fish、PowerShell（以及 Elvish、Fig）可直接加载的补全定义，实现Tab键联想输入。读完本文，你将掌握forc completions --shell=<target>在各主流 shell 与 macOS/Linux/Windows 环境下的安装步骤、脚本落盘位置与生效方式，并理解该命令背后的 clap/clap_complete 生成原理与仓库内的自动化测试保障。

命令概览：forc completions能做什么

在 Sway 仓库中，forc completions由 forc/src/cli/commands/completions.rs 实现，其命令注释明确为"Generate tab-completion scripts for your shell"（为你的 shell 生成 Tab 补全脚本）。它隶属于 forc/src/cli/mod.rs 中定义的Forc子命令枚举（Completions(CompletionsCommand)），是forc内建子命令之一。

核心用法十分简单——指定一个目标 shell 即可：

forc completions --shell=<bash|zsh|fish|powershell|elvish|fig>

生成脚本会被直接输出到标准输出（stdout），因此你可以自由重定向到任意文件，具体存放位置取决于你使用的 shell 与操作系统。从源码看，--shell选项同时支持短参数-T（#[clap(short = 'T', long, value_enum)]），并可通过Tab键获得枚举值提示。

支持的补全目标

从 completions.rs 的Target枚举可以看出，除文档中详细介绍的 Bash、Fish、Zsh、PowerShell 外，forc completions还额外支持两个目标：

其中fig走clap_complete_fig::Fig生成器，其余五个目标统一走clap_completecrate 的Shell枚举，最终由generate(gen, cmd, cmd.get_name(), &mut std::io::stdout())把补全脚本写到 stdout。所谓“输出到 stdout、由你决定重定向到哪里”正是这一行代码的直接体现。

Bash：安装补全脚本

GNU/Linux 与类 Unix 系统

Bash 的补全文件通常存放在两处：

• 系统级命令：/etc/bash_completion.d/
• 用户级命令：~/.local/share/bash-completion/completions

推荐将forc安装为当前用户的用户级补全：

mkdir -p ~/.local/share/bash-completion/completions forc completions --shell=bash >> ~/.local/share/bash-completion/completions/forc

第二条命令把补全脚本追加（>>）到名为forc的文件中。安装完成后，你可能需要注销并重新登录 shell 会话，改动才会生效。

macOS / Homebrew

在 macOS 上，Homebrew 会将 bash 补全文件存放在 Homebrew 目录内。前提是先通过bash-completion这个 brew formula 安装好补全框架，然后执行：

mkdir -p $(brew --prefix)/etc/bash_completion.d forc completions --shell=bash > $(brew --prefix)/etc/bash_completion.d/forc.bash-completion

这里使用>直接写入（覆盖）目标文件，文件名取为forc.bash-completion。注意$(brew --prefix)会在命令执行时动态展开为 Homebrew 的实际安装前缀（通常为/opt/homebrew或/usr/local）。

Fish：安装补全脚本

Fish 的补全文件惯例存放在$HOME/.config/fish/completions：

mkdir -p ~/.config/fish/completions forc completions --shell=fish > ~/.config/fish/completions/forc.fish

生成的forc.fish即为 Fish 可自动加载的补全定义文件。与 Bash 类似，安装后可能需要注销并重新登录会话才生效。

Zsh：借助 $fpath 加载补全

Zsh 的补全惯例是存放在$fpath变量列出的任意目录中。有两种做法：把生成脚本直接放进某个已有目录，或把自建目录加入$fpath。如果对用哪个目录没把握，自建目录往往最稳妥。示例流程如下：

第一步，创建目录（此处以$HOME下的隐藏目录为例）：

mkdir ~/.zfunc

第二步，在.zshrc中compinit之前加入该目录到$fpath：

fpath+=~/.zfunc

第三步，生成补全脚本并写入该目录，文件名必须是_forc（zsh 补全函数约定以下划线前缀命名）：

forc completions --shell=zsh > ~/.zfunc/_forc

最后，让新补全生效有两种方式：注销并重新登录，或直接重启当前 zsh 会话：

exec zsh

exec zsh会用新的 zsh 进程替换当前 shell，从而立即重新读取.zshrc并执行compinit，无需退出终端窗口。

自定义存放位置（CUSTOM LOCATIONS）

如果你希望把补全脚本放到其他位置——例如$HOME下的自定义目录——完全可行。需要做的只是在登录脚本中加入相应指令，让 shell 在启动时加载它。以 Bash 为例即是在.bashrc中source该文件；zsh 则是在.zshrc中将其目录加入$fpath或直接source。具体指令写法请查阅你所使用 shell 的官方文档。

PowerShell：写入 profile 文件

PowerShell 补全脚本要求PowerShell v5.0+（Windows 10 自带，Windows 7/8.1 需单独下载安装）。

第一步，检查是否已设置 profile：

Test-Path $profile

如果返回False，执行以下命令创建 profile 文件：

New-Item -path $profile -type file -force

第二步，打开$profile指向的文件（若刚用New-Item创建，其默认路径为${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1）。

第三步，把补全脚本追加进 profile 即可：

forc completions --shell=powershell >> ${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1

当然也可以先把补全内容单独保存为文件，再在 profile 中source它，两种方式等价。之后新开 PowerShell 窗口即可使用Tab补全forc的子命令与参数。

底层原理：clap 命令树与补全生成

forc completions之所以能生成覆盖全部子命令的补全，关键在于它直接基于整个 Forc CLI 的命令定义生成脚本。源码中：

pub(crate) fn exec(command: Command) -> ForcResult<()> { let mut cmd = super::super::Opt::command(); match command.target { Target::Fig => print_completions(clap_complete_fig::Fig, &mut cmd), Target::Bash => print_completions(Shell::Bash, &mut cmd), // ... } Ok(()) } fn print_completions<G: Generator>(gen: G, cmd: &mut ClapCommand) { generate(gen, cmd, cmd.get_name().to_string(), &mut std::io::stdout()); }

Opt::command()通过 clap 的CommandFactory把 forc/src/cli/mod.rs 中定义的完整命令树（含add、addr2line、build、check、clean、completions、init、new、parse-bytecode、plugins、test、update、template、remove、contract-id、predicate-root等全部内建子命令，以及全局参数-v/--verbose、-s/--silent、-L/--log-level）反射为 clap 命令对象，再由clap_complete的generate针对不同 shell 语法渲染成补全脚本。这意味着每次新版本forc增减子命令或参数，重新生成补全脚本即可自动同步，无需手工维护。

自动化测试保障

仓库为补全生成提供了基于 PTY 的集成测试，见 completions.rs 的test模块：测试分别用completest_pty的BashRuntimeBuilder、ZshRuntimeBuilder、FishRuntimeBuilder启动真实的 shell 运行时，注册forc补全脚本后模拟输入forc <Tab><Tab>，并断言输出中包含Forc::possible_values()列出的每个子命令名。这从源码层面验证了生成的补全脚本确实能在真实 shell 中触发并列出全部子命令。

进阶：结合forc全局参数使用

forc completions本身支持-T/--shell指定目标，同时也接受forc的全局参数，例如静默模式：

forc completions --shell=zsh --silent

全局参数在 forc/src/cli/mod.rs 中定义为global = true，因此可以出现在任何子命令之后。生成补全脚本时它们也会一并被写入补全定义。

关联阅读：该文档在仓库文档体系中的位置

本文对应的forc_completions.md位于 scripts/mdbook-forc-documenter/examples/forc_completions.md，它是 Sway 仓库中mdbook-forc-documenter 预处理器的 examples 目录的一部分。该预处理器（实现于 scripts/mdbook-forc-documenter/src/lib.rs）在每次mdbook build时自动运行：它通过执行forc --help与forc <subcommand> --help获取所有命令的最新帮助文本，再依据 SUMMARY.md 中的章节结构，把生成的命令文档注入 Sway Book 的 Forc Reference 章节；同时，examples 目录下与命令同名的 Markdown 文件会被作为“示例”章节附加到对应命令文档末尾（见inject_content逻辑与 README.md 中“Adding an example”一节）。

因此，你在 Sway Book 的 Forc Reference 中看到的forc completions页面，其“DISCUSSION”部分即来自本文档，而用法、参数、子命令等章节则由预处理器从forc completions --help实时生成。docs 目录下其他命令文档（如 forc_build.md）采用完全相同的机制。若想给某条命令补充示例，只需在 examples 目录新增与该命令同名的 snake_case 文件即可，无需改动预处理器本身。

常见问题与排错

生成了脚本但 Tab 补全不生效：绝大多数情况是文件没放在 shell 期望的位置，或未重新加载 shell。Bash 检查~/.local/share/bash-completion/completions/forc是否存在且非空；zsh 确认~/.zfunc已加入$fpath且在compinit之前；Fish 确认文件名严格为forc.fish；PowerShell 确认 profile 文件确实被加载（可执行echo $profile查看路径）。

目标文件命名：不同 shell 对补全文件名有约定（zsh 为_forc，Fish 为forc.fish，Bash 无强制后缀但建议统一），请按上文各节约定命名，避免 shell 忽略该文件。

输出被截断：脚本输出到 stdout，务必使用>（覆盖）或>>（追加）重定向到文件，不要在终端直接运行forc completions --shell=bash后手动复制，以免因终端换行处理导致脚本损坏。

【免费下载链接】sway🌴 Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway