如何为 GetWebP CLI 生成 man 页面并安装 Bash、Zsh 和 Fish 的 tab 补全脚本。

man 页面和 shell 补全

如何为 GetWebP CLI 生成 man 页面并安装 Bash、Zsh 和 Fish 的 tab 补全脚本。

另请参阅： 命令参考 | 入门 | README

目录 #

man 页面
shell 补全
- Bash
- Zsh
- Fish
Homebrew 公式集成

man 页面 #

生成方法 #

GetWebP man 页面维护为手写的 roff 源文件。这提供了对格式化的完全控制并避免了构建工具依赖。标志和行为的事实来源是 commands.md；man 页面在 troff 格式中镜像该内容。

另一种方法是使用 marked-man、ronn 或 pandoc 等工具从结构化数据（例如 JSON 架构或 CLI 的 --help 输出）生成 man 页面。对于 GetWebP，首选手写方法，因为 CLI 表面很小（4 个命令），不太可能经常变化。

安装 man 页面 #

将下面的 roff 源代码保存到名为 getwebp.1 的文件中，然后安装它：

# macOS / Linux
sudo mkdir -p /usr/local/share/man/man1
sudo cp getwebp.1 /usr/local/share/man/man1/getwebp.1
sudo gzip -f /usr/local/share/man/man1/getwebp.1
 
# 验证
man getwebp

要卸载：

sudo rm -f /usr/local/share/man/man1/getwebp.1.gz

man 页面源 #

将以下内容保存为 getwebp.1：

.TH GETWEBP 1 "2026-04-02" "getwebp 1.0.1" "GetWebP CLI 手册"
.SH NAME
getwebp \- 批量转换图像为 WebP 格式
.SH SYNOPSIS
.B getwebp convert
.RI [ path ]
.RI [ options ]
.br
.B getwebp auth
.I license-key
.RI [ options ]
.br
.B getwebp status
.RI [ options ]
.br
.B getwebp logout
.RI [ options ]
.SH DESCRIPTION
.B getwebp
转换 JPG、PNG、BMP 和 WebP 图像为优化的 WebP 格式。
它支持整个目录的批量转换、并行处理
(Pro 计划) 和用于 CI/CD 管道的结构化 JSON 输出。
.PP
原始文件永远不会被修改或删除。
.SH COMMANDS
.TP
.B convert \fR[\fIpath\fR] [\fIoptions\fR]
将一个或多个图像转换为 WebP 格式。位置
.I path
参数和
.B \-i
标志可互换。如果两者都提供，位置参数
优先。
.TP
.B auth \fIlicense-key\fR
激活许可证密钥以解锁 Pro 功能。将许可证
绑定到当前设备。
.TP
.B status
显示当前许可证信息、计划层级、过期日期和设备使用情况。
.TP
.B logout
从此设备解绑许可证，释放设备插槽。需要
网络访问。
.SH CONVERT OPTIONS
.TP
.BR \-i ", " \-\-input " " \fIpath\fR
输入文件或目录（位置参数的替代）。
.TP
.BR \-o ", " \-\-output " " \fIpath\fR
已转换文件的输出目录。默认为与源相同的目录。
.TP
.BR \-q ", " \-\-quality " " \fInumber\fR
WebP 质量，1\-\-100。默认值：80。
.TP
.BR \-r ", " \-\-recursive
递归处理子目录中的图像。
.TP
.B \-\-concurrency " " \fInumber\fR
并行工作者数（最多 32）。默认值：CPU 核心数减 1。
仅限 Pro 计划；在免费计划上被忽略。
.TP
.B \-\-dry\-run
预览将被转换的文件而不写入任何文件。
.TP
.B \-\-skip\-existing
如果输出路径已存在 .webp 文件则跳过转换。
.SH LOGOUT OPTIONS
.TP
.BR \-f ", " \-\-force
跳过交互式确认提示。
.SH GLOBAL OPTIONS
.TP
.BR \-v ", " \-\-version
打印 CLI 版本并退出。
.TP
.B \-\-help
显示帮助文本并退出。
.TP
.B \-\-json
在 stdout 上发出结构化 JSON 输出。人类可读的消息转到
stderr。在所有命令上可用。
.TP
.B \-\-verbose
启用详细输出。
.TP
.B \-\-debug
启用调试输出。隐含
.BR \-\-verbose 。
.SH EXIT STATUS
.TP
.B 0
所有文件处理成功。
.TP
.B 1
常规错误。
.TP
.B 2
部分失败（某些文件失败）。
.TP
.B 3
许可证 / 认证错误。
.TP
.B 4
网络错误。
.SH EXAMPLES
转换单个图像：
.PP
.RS
.B getwebp convert photo.png
.RE
.PP
使用自定义输出转换目录：
.PP
.RS
.B getwebp convert ./images \-o ./dist/images
.RE
.PP
高质量，跳过已转换的文件：
.PP
.RS
.B getwebp convert ./images \-q 95 \-\-skip\-existing
.RE
.PP
使用 8 个并行工作者的递归扫描：
.PP
.RS
.B getwebp convert ./images \-r \-\-concurrency 8
.RE
.PP
用于 CI/CD 的 JSON 输出：
.PP
.RS
.B getwebp convert ./images \-\-json
.RE
.PP
激活许可证：
.PP
.RS
.B getwebp auth XXXX\-XXXX\-XXXX\-XXXX
.RE
.PP
检查许可证状态：
.PP
.RS
.B getwebp status \-\-json
.RE
.PP
无确认注销：
.PP
.RS
.B getwebp logout \-\-force
.RE
.SH FREE PLAN LIMITATIONS
在没有激活许可证的情况下：每次运行最多 20 个文件，文件之间
有 3 秒延迟，仅限串行处理（\-\-concurrency 被忽略）。
.SH SEE ALSO
.UR https://getwebp.com
GetWebP 网站
.UE ,
.UR https://getwebp.com/pricing
定价
.UE
.SH AUTHORS
GetWebP 团队。

shell 补全 #

Bash 补全 #

将以下内容保存为 getwebp.bash（或您补全目录中的 getwebp）。

有关 Bash 补全脚本的详细信息，请参阅上面保存的源文件。

安装 Bash 补全 #

# 选项 A：系统范围（需要 root）
sudo cp getwebp.bash /etc/bash_completion.d/getwebp
 
# 选项 B：每用户
mkdir -p ~/.local/share/bash-completion/completions
cp getwebp.bash ~/.local/share/bash-completion/completions/getwebp
 
# 选项 C：直接在 ~/.bashrc 中源代码
echo 'source /path/to/getwebp.bash' >> ~/.bashrc

重新加载您的 shell 或运行 source ~/.bashrc 以使补全生效。

Zsh 补全 #

将以下内容保存为 _getwebp。

参考源文件了解详细的 Zsh 补全实现。

安装 Zsh 补全 #

# 选项 A：系统范围
sudo mkdir -p /usr/local/share/zsh/site-functions
sudo cp _getwebp /usr/local/share/zsh/site-functions/
 
# 选项 B：每用户
mkdir -p ~/.zsh/completions
cp _getwebp ~/.zsh/completions/
 
# 然后在 ~/.zshrc 中添加
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Fish 补全 #

对于 Fish shell 用户，参考源文件中的实现。

安装 Fish 补全 #

mkdir -p ~/.config/fish/completions
cp getwebp.fish ~/.config/fish/completions/

Homebrew 公式集成 #

如果您将 GetWebP 作为 Homebrew 公式分发，包括 man 页面和 shell 补全：

class Getwebp < Formula
  desc "批量转换图像为 WebP 格式"
  url "https://github.com/getwebp/cli/releases/download/v1.0.1/getwebp-macos-arm64"
  sha256 "..."
 
  def install
    bin.install "getwebp-macos-arm64" => "getwebp"
    
    # 安装 man 页面
    man1.install "getwebp.1"
    
    # 安装 shell 补全
    bash_completion.install "getwebp.bash" => "getwebp"
    zsh_completion.install "_getwebp"
    fish_completion.install "getwebp.fish"
  end
end

文档

man 页面和 shell 补全