man 页面和 shell 补全

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

man 页面和 shell 补全

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

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

目录 #

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

man 页面 #

生成方法 #

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

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

安装 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-11" "getwebp 1.2.1" "GetWebP CLI 手册"
.SH NAME
getwebp \- 批量转换图像为 WebP 格式
.SH SYNOPSIS
.B getwebp convert
.RI [ path ]
.RI [ options ]
.br
.B getwebp watch
.I 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 管道的结构化 NDJSON 输出。
.PP
原始文件永远不会被修改或删除。
.SH COMMANDS
.TP
.B convert \fR[\fIpath\fR] [\fIoptions\fR]
将一个或多个图像转换为 WebP 格式。位置
.I path
参数和
.B \-i
标志可互换。如果两者都提供，位置参数
优先。
.TP
.B watch \fR[\fIpaths...\fR] [\fIoptions\fR]
监视一个目录的文件变更并自动将
新的或修改的图像转换为 WebP。仅限 Pro 计划。运行直到 Ctrl+C。
.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
.B \-\-quality " " \fInumber\fR
WebP 质量，1\-\-100。覆盖 SSIM 自动质量。
.TP
.B \-\-no\-auto\-quality
禁用 SSIM 自动质量；使用固定质量 80。
.TP
.BR \-r ", " \-\-recursive
递归处理子目录中的图像。
.TP
.B \-\-concurrency " " \fInumber\fR
并行工作者数（最多 32）。默认值：CPU 核心数减 1。
仅限 Pro 计划；在免费计划上被忽略。
.TP
.B \-\-dry\-run
预览将被转换的文件而不写入任何文件。
.TP
.B \-\-skip\-existing
如果输出路径已存在 .webp 文件则跳过转换。
.TP
.B \-\-manifest " " \fIpath\fR
将 JSON 资源指纹清单写入指定路径。
.SH WATCH OPTIONS
.TP
.BR \-o ", " \-\-output " " \fIpath\fR
将转换后的文件镜像到此目录（保留目录树）。
.TP
.B \-\-quality " " \fInumber\fR
固定 WebP 质量，1\-\-100。
.TP
.B \-\-no\-auto\-quality
禁用 SSIM 自动质量；使用固定质量 80。
.TP
.B \-\-concurrency " " \fInumber\fR
覆盖并行工作者数量。
.TP
.B \-\-stability\-threshold " " \fIms\fR
文件写入稳定性检测窗口（毫秒，默认：1000）。
.TP
.B \-\-backfill
启动时处理监视目录中的所有现有文件。
.TP
.B \-\-no\-color
禁用 ANSI 颜色。
.SH GLOBAL OPTIONS
.TP
.BR \-V ", " \-\-version
打印 CLI 版本并退出。
.TP
.BR \-h ", " \-\-help
显示帮助文本并退出。
.TP
.BR \-j ", " \-\-json
在 stdout 上发出 NDJSON 事件。人类可读的消息转到
stderr。在所有命令上可用。
.TP
.BR \-v ", " \-\-verbose
启用详细输出。
.TP
.BR \-q ", " \-\-quiet
在 stderr 上抑制 info 和 warn；错误仍会打印。
.TP
.BR \-f ", " \-\-force
跳过交互式确认提示。
.TP
.B \-\-debug
启用调试输出。隐含
.BR \-\-verbose 。
.SH EXIT STATUS
.TP
.B 0
所有操作成功完成。
.TP
.B 1
常规错误（未分类）。
.TP
.B 2
用法错误（无效标志、缺少参数、错误的值）。
.TP
.B 3
部分失败（某些文件失败，其他成功）。
.TP
.B 4
认证错误（许可证无效、过期或设备限制）。
.TP
.B 5
网络错误（API 不可访问或超时）。
.TP
.B 6
免费层级限制已达（20 文件上限；某些文件被跳过）。
.TP
.B 75
活跃 watch 会话期间许可证被撤销。
.TP
.B 76
Watch 会话期间磁盘已满（重试预算耗尽）。
.TP
.B 130
SIGINT (Ctrl+C)。
.TP
.B 143
SIGTERM。
.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 \-\-quality 95 \-\-skip\-existing
.RE
.PP
使用 8 个并行工作者的递归扫描：
.PP
.RS
.B getwebp convert ./images \-r \-\-concurrency 8
.RE
.PP
用于 CI/CD 的 NDJSON 输出：
.PP
.RS
.B getwebp convert ./images \-\-json
.RE
.PP
监视目录（Pro）：
.PP
.RS
.B getwebp watch ./images \-o ./dist
.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 被忽略），以及
无法访问 watch 命令。
.SH SEE ALSO
.UR https://getwebp.com
GetWebP 网站
.UE ,
.UR https://getwebp.com/pricing
定价
.UE
.SH AUTHORS
GetWebP 团队。

shell 补全 #

Bash 补全 #

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

# getwebp bash completion
# Install: copy to /etc/bash_completion.d/getwebp
#   or source from ~/.bashrc
 
_getwebp() {
    local cur prev words cword
    _init_completion || return
 
    local commands="convert watch auth status logout"
    local global_flags="-V --version -h --help -j --json -v --verbose -q --quiet -f --force --debug"
 
    # Determine which command (if any) has been typed
    local cmd=""
    local i
    for ((i = 1; i < cword; i++)); do
        case "${words[i]}" in
            convert|watch|auth|status|logout)
                cmd="${words[i]}"
                break
                ;;
        esac
    done
 
    # No command yet — complete commands and global flags
    if [[ -z "$cmd" ]]; then
        COMPREPLY=($(compgen -W "$commands $global_flags" -- "$cur"))
        return
    fi
 
    case "$cmd" in
        convert)
            local convert_flags="-i --input -o --output --quality --no-auto-quality -r --recursive --concurrency --dry-run --skip-existing --manifest --json --verbose --debug"
            case "$prev" in
                -i|--input|-o|--output|--manifest)
                    # Complete file/directory paths
                    _filedir
                    return
                    ;;
                --quality)
                    # Suggest common quality values
                    COMPREPLY=($(compgen -W "60 70 75 80 85 90 95 100" -- "$cur"))
                    return
                    ;;
                --concurrency)
                    COMPREPLY=($(compgen -W "1 2 4 8 16 32" -- "$cur"))
                    return
                    ;;
            esac
            if [[ "$cur" == -* ]]; then
                COMPREPLY=($(compgen -W "$convert_flags" -- "$cur"))
            else
                # Positional argument: file/directory path
                _filedir
            fi
            ;;
        watch)
            local watch_flags="-o --output --quality --no-auto-quality --concurrency --stability-threshold --backfill --no-color --json --verbose --debug"
            case "$prev" in
                -o|--output)
                    _filedir -d
                    return
                    ;;
                --quality)
                    COMPREPLY=($(compgen -W "60 70 75 80 85 90 95 100" -- "$cur"))
                    return
                    ;;
                --concurrency)
                    COMPREPLY=($(compgen -W "1 2 4 8 16 32" -- "$cur"))
                    return
                    ;;
            esac
            if [[ "$cur" == -* ]]; then
                COMPREPLY=($(compgen -W "$watch_flags" -- "$cur"))
            else
                _filedir -d
            fi
            ;;
        auth)
            # auth takes a license key (no completion) and optional flags
            if [[ "$cur" == -* ]]; then
                COMPREPLY=($(compgen -W "--json --verbose --debug" -- "$cur"))
            fi
            ;;
        status)
            if [[ "$cur" == -* ]]; then
                COMPREPLY=($(compgen -W "--json --verbose --debug" -- "$cur"))
            fi
            ;;
        logout)
            if [[ "$cur" == -* ]]; then
                COMPREPLY=($(compgen -W "-f --force --json --verbose --debug" -- "$cur"))
            fi
            ;;
    esac
}
 
complete -F _getwebp getwebp

安装 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。

#compdef getwebp
 
# getwebp zsh completion
# Install: copy to a directory in your $fpath (e.g., /usr/local/share/zsh/site-functions/)
 
_getwebp() {
    local -a commands
    commands=(
        'convert:将图像转换为 WebP 格式'
        'watch:监视目录并在变更时自动转换（Pro）'
        'auth:激活许可证密钥'
        'status:显示许可证和版本信息'
        'logout:从此设备解绑许可证'
    )
 
    local -a global_flags
    global_flags=(
        '(-V --version)'{-V,--version}'[打印 CLI 版本并退出]'
        '(-h --help)'{-h,--help}'[显示帮助文本并退出]'
        '(-j --json)'{-j,--json}'[在 stdout 上发出 NDJSON 事件]'
        '(-v --verbose)'{-v,--verbose}'[启用详细输出]'
        '(-q --quiet)'{-q,--quiet}'[在 stderr 上抑制 info 和 warn]'
        '(-f --force)'{-f,--force}'[跳过确认提示]'
        '--debug[启用调试输出（隐含 --verbose）]'
    )
 
    _arguments -C \
        '1:command:->command' \
        '*::arg:->args' \
        && return
 
    case "$state" in
        command)
            _describe -t commands 'getwebp command' commands
            _values 'global flags' $global_flags
            ;;
        args)
            case "${words[1]}" in
                convert)
                    _arguments \
                        '1:path:_files' \
                        '(-i --input)'{-i,--input}'[输入文件或目录]:path:_files' \
                        '(-o --output)'{-o,--output}'[输出目录]:path:_files -/' \
                        '--quality[WebP 质量 1-100]:quality:(60 70 75 80 85 90 95 100)' \
                        '--no-auto-quality[使用固定质量 80 而非自动]' \
                        '(-r --recursive)'{-r,--recursive}'[递归处理子目录]' \
                        '--concurrency[并行工作者数（最多 32）]:workers:(1 2 4 8 16 32)' \
                        '--dry-run[预览文件而不转换]' \
                        '--skip-existing[如果 .webp 已存在则跳过]' \
                        '--manifest[写入资源指纹清单]:path:_files' \
                        '--json[CI 管道的 NDJSON 输出]' \
                        '--verbose[启用详细输出]' \
                        '--debug[启用调试输出]'
                    ;;
                watch)
                    _arguments \
                        ':path:_files -/' \
                        '(-o --output)'{-o,--output}'[镜像输出目录]:path:_files -/' \
                        '--quality[固定 WebP 质量 1-100]:quality:(60 70 75 80 85 90 95 100)' \
                        '--no-auto-quality[使用固定质量 80]' \
                        '--concurrency[并行工作者]:workers:(1 2 4 8 16 32)' \
                        '--stability-threshold[文件稳定性窗口（毫秒）]:ms:' \
                        '--backfill[启动时处理现有文件]' \
                        '--no-color[禁用 ANSI 颜色]' \
                        '--json[NDJSON 输出]' \
                        '--verbose[启用详细输出]' \
                        '--debug[启用调试输出]'
                    ;;
                auth)
                    _arguments \
                        '1:license-key:' \
                        '--json[JSON 输出]' \
                        '--verbose[启用详细输出]' \
                        '--debug[启用调试输出]'
                    ;;
                status)
                    _arguments \
                        '--json[JSON 输出]' \
                        '--verbose[启用详细输出]' \
                        '--debug[启用调试输出]'
                    ;;
                logout)
                    _arguments \
                        '(-f --force)'{-f,--force}'[跳过确认提示]' \
                        '--json[JSON 输出]' \
                        '--verbose[启用详细输出]' \
                        '--debug[启用调试输出]'
                    ;;
            esac
            ;;
    esac
}
 
_getwebp "$@"

安装 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 用户，将以下内容保存为 getwebp.fish。

# getwebp fish completion
# Install: copy to ~/.config/fish/completions/getwebp.fish
 
# Disable file completions by default (we enable them per-subcommand)
complete -c getwebp -f
 
# Helper: true when no subcommand has been entered yet
function __getwebp_no_subcommand
    set -l tokens (commandline -opc)
    for t in $tokens[2..]
        switch $t
            case convert watch auth status logout
                return 1
        end
    end
    return 0
end
 
# Helper: true when the given subcommand is active
function __getwebp_using_subcommand
    set -l tokens (commandline -opc)
    for t in $tokens[2..]
        switch $t
            case $argv[1]
                return 0
        end
    end
    return 1
end
 
# --- Top-level completions ---
complete -c getwebp -n '__getwebp_no_subcommand' -a convert  -d '将图像转换为 WebP 格式'
complete -c getwebp -n '__getwebp_no_subcommand' -a watch    -d '监视目录并自动转换（Pro）'
complete -c getwebp -n '__getwebp_no_subcommand' -a auth     -d '激活许可证密钥'
complete -c getwebp -n '__getwebp_no_subcommand' -a status   -d '显示许可证和版本信息'
complete -c getwebp -n '__getwebp_no_subcommand' -a logout   -d '从此设备解绑许可证'
complete -c getwebp -n '__getwebp_no_subcommand' -s V -l version  -d '打印 CLI 版本'
complete -c getwebp -n '__getwebp_no_subcommand' -s h -l help     -d '显示帮助文本'
complete -c getwebp -n '__getwebp_no_subcommand' -s j -l json     -d 'NDJSON 输出'
complete -c getwebp -n '__getwebp_no_subcommand' -s v -l verbose  -d '启用详细输出'
complete -c getwebp -n '__getwebp_no_subcommand' -s q -l quiet    -d '抑制 info 和 warn'
complete -c getwebp -n '__getwebp_no_subcommand' -s f -l force    -d '跳过确认提示'
complete -c getwebp -n '__getwebp_no_subcommand' -l debug         -d '启用调试输出'
 
# --- convert ---
complete -c getwebp -n '__getwebp_using_subcommand convert' -s i -l input           -r -F -d '输入文件或目录'
complete -c getwebp -n '__getwebp_using_subcommand convert' -s o -l output          -r -F -d '输出目录'
complete -c getwebp -n '__getwebp_using_subcommand convert'      -l quality         -r -x -a '60 70 75 80 85 90 95 100' -d 'WebP 质量 1-100'
complete -c getwebp -n '__getwebp_using_subcommand convert'      -l no-auto-quality      -d '使用固定质量 80'
complete -c getwebp -n '__getwebp_using_subcommand convert' -s r -l recursive            -d '处理子目录'
complete -c getwebp -n '__getwebp_using_subcommand convert'      -l concurrency     -r -x -a '1 2 4 8 16 32' -d '并行工作者（最多 32）'
complete -c getwebp -n '__getwebp_using_subcommand convert'      -l dry-run              -d '预览而不转换'
complete -c getwebp -n '__getwebp_using_subcommand convert'      -l skip-existing        -d '如果 .webp 已存在则跳过'
complete -c getwebp -n '__getwebp_using_subcommand convert'      -l manifest        -r -F -d '写入资源指纹清单'
complete -c getwebp -n '__getwebp_using_subcommand convert'      -l json                 -d 'NDJSON 输出'
complete -c getwebp -n '__getwebp_using_subcommand convert'      -l verbose              -d '启用详细输出'
complete -c getwebp -n '__getwebp_using_subcommand convert'      -l debug                -d '启用调试输出'
# Allow file path completion for positional arg
complete -c getwebp -n '__getwebp_using_subcommand convert' -F
 
# --- watch ---
complete -c getwebp -n '__getwebp_using_subcommand watch' -s o -l output             -r -F -d '镜像输出目录'
complete -c getwebp -n '__getwebp_using_subcommand watch'      -l quality            -r -x -a '60 70 75 80 85 90 95 100' -d '固定质量 1-100'
complete -c getwebp -n '__getwebp_using_subcommand watch'      -l no-auto-quality         -d '使用固定质量 80'
complete -c getwebp -n '__getwebp_using_subcommand watch'      -l concurrency        -r -x -a '1 2 4 8 16 32' -d '并行工作者'
complete -c getwebp -n '__getwebp_using_subcommand watch'      -l stability-threshold -r  -d '文件稳定性窗口（毫秒）'
complete -c getwebp -n '__getwebp_using_subcommand watch'      -l backfill                -d '启动时处理现有文件'
complete -c getwebp -n '__getwebp_using_subcommand watch'      -l no-color                -d '禁用 ANSI 颜色'
complete -c getwebp -n '__getwebp_using_subcommand watch'      -l json                    -d 'NDJSON 输出'
complete -c getwebp -n '__getwebp_using_subcommand watch'      -l verbose                 -d '启用详细输出'
complete -c getwebp -n '__getwebp_using_subcommand watch'      -l debug                   -d '启用调试输出'
complete -c getwebp -n '__getwebp_using_subcommand watch' -F
 
# --- auth ---
complete -c getwebp -n '__getwebp_using_subcommand auth' -l json    -d 'NDJSON 输出'
complete -c getwebp -n '__getwebp_using_subcommand auth' -l verbose -d '启用详细输出'
complete -c getwebp -n '__getwebp_using_subcommand auth' -l debug   -d '启用调试输出'
 
# --- status ---
complete -c getwebp -n '__getwebp_using_subcommand status' -l json    -d 'NDJSON 输出'
complete -c getwebp -n '__getwebp_using_subcommand status' -l verbose -d '启用详细输出'
complete -c getwebp -n '__getwebp_using_subcommand status' -l debug   -d '启用调试输出'
 
# --- logout ---
complete -c getwebp -n '__getwebp_using_subcommand logout' -s f -l force   -d '跳过确认提示'
complete -c getwebp -n '__getwebp_using_subcommand logout'      -l json    -d 'NDJSON 输出'
complete -c getwebp -n '__getwebp_using_subcommand logout'      -l verbose -d '启用详细输出'
complete -c getwebp -n '__getwebp_using_subcommand logout'      -l debug   -d '启用调试输出'

安装 Fish 补全 #

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

Homebrew 公式集成 #

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

class Getwebp < Formula
  desc "批量转换图像为优化的 WebP 格式"
  homepage "https://getwebp.com"
  version "1.2.1"
  license "MIT"
 
  # ... platform-specific url/sha256 blocks ...
 
  def install
    bin.install "getwebp"
 
    # 安装 man 页面
    man1.install "getwebp.1"
 
    # 安装 shell 补全
    bash_completion.install "completions/getwebp.bash" => "getwebp"
    zsh_completion.install  "completions/_getwebp"
    fish_completion.install "completions/getwebp.fish"
  end
 
  test do
    assert_match "getwebp/#{version}", shell_output("#{bin}/getwebp -V")
  end
end