About MacWave

关于MacWave

MacWave is a package manager for macOS, built to distribute the command-line tools that macOS software developers rely on. Its project, LinuxWave, covers Linux.

MacWave 是一个面向 macOS 的包管理器，用于分发 macOS 软件开发者日常依赖的命令行工具。Linux 由项目 LinuxWave 覆盖。

Why MacWave

为什么选择 MacWave

• Small on disk. The installer fetches individual files rather than cloning the repository, and there is no package cache to keep in sync.
• One command per package. Common tools are installed by name, without hunting for release pages.
• Versioned by design. Every binary lives under package@version, so several versions coexist and none of them shadow a system tool.
• Optional unversioned links. wave link <package> creates a plain package shortcut that points at the highest installed version and re-points itself whenever versions are installed or removed.
• Isolated by construction. Everything MacWave installs stays inside its own directories; it never overwrites or links against macOS system libraries, so even a major macOS upgrade leaves it intact.
• No stale metadata. Package data is read from the MacWaveOrg/infosource repository at request time.
• Ten archive formats, covered by CI. Extensionless binaries, .zip, .tar.gz, .tar.bz2, .tar.xz, .tar, .gz, .xz, .bz2, and .conda.
• Checksum before extraction. A package whose SHA256 is missing or does not match is refused, never installed with a warning.
• Resumable downloads. An interrupted transfer continues with -C.
• Transparent implementation. Python and Shell only. The interpreter is bundled, so no runtime has to be installed and no behaviour is hidden behind one.
• Dependencies handled for you. Packages that need libraries declare them; MacWave installs, tracks and removes those libraries by reference count.

• 占用小。 安装器按文件拉取，而不是 clone 整个仓库；也不保留需要同步的软件包缓存。
• 一条命令装一个软件包。 常用工具按名字安装，不必再逐个寻找发布页。
• 版本化存储。 每个二进制文件都存放在 package@version 之下，多个版本可以共存，且都不会遮蔽系统工具。
• 可选的免版本号链接。 wave link <软件包> 会创建一个不带版本号的 软件包 快捷方式，指向已安装的最高版本；安装或卸载版本时，它会自动改指。
• 天然隔离。 MacWave 安装的一切都留在自己的目录中，绝不覆盖或链接 macOS 系统库，因此即使跨越大版本升级 macOS，环境依然完整可用。
• 元数据不会过期。 软件包数据在请求时从 MacWaveOrg/infosource 仓库读取。
• 十种归档格式，均由 CI 覆盖。 无扩展名二进制文件、.zip、.tar.gz、.tar.bz2、.tar.xz、.tar、.gz、.xz、.bz2 与 .conda。
• 先校验，后解压。 缺少 SHA256 或校验不符的软件包会被拒绝，绝不「给出警告后照常安装」。
• 支持断点续传。 传输中断后可用 -C 继续。
• 实现透明。 只用 Python 与 Shell，并自带解释器 —— 无需另装运行时，行为也没有藏在运行时里。
• 依赖自动处理。 需要库的软件包会在记录中声明；MacWave 按引用计数安装、追踪并移除这些库。

Supported macOS Version

支持的 macOS 版本

macOS Monterey 12 and above

macOS Monterey 12 及以上

Install MacWave

安装 MacWave

In the terminal, run:

在终端中运行：

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/MacWaveOrg/MacWave/HEAD/lib/install.sh)"

(If you are using bash instead of zsh, run source ~/.bashrc)

（如果你使用的是 bash 而非 zsh，请运行 source ~/.bashrc）

Requirements: macOS Monterey 12 or later, Xcode Command Line Tools.
You do not need to install Python — MacWave bundles its own interpreter.

环境要求：macOS Monterey 12 及以上、Xcode Command Line Tools。
你不需要自己安装 Python —— MacWave 自带解释器。

This repository holds source, not an installation. Running wave from inside a clone, or adding directories from the clone to PATH, fails by design.

本仓库存放的是源码，不是安装结果。在 clone 里运行 wave、或把 clone 中的目录加入 PATH，都会按设计失败。

Unattended install

无人值守安装

For scripts and batch use, the installer takes flags so it never waits for input. Options go after --, which ends bash’s own options:

面向脚本与批量场景，安装器提供若干参数，全程不会停下来等待输入。参数放在 -- 之后 —— -- 会结束 bash 自身的选项：

# straight from the repository
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/MacWaveOrg/MacWave/HEAD/lib/install.sh)" \
  -- --ci --dir-option=1

--ci (same as --CI) answers the directory menu and the agreement automatically. It needs passwordless sudo, or root, when the chosen directory requires privilege. --dir-option=N picks menu entry N (1-4 on Intel, 1-3 on Apple silicon); for the custom entry, append the path after =, as in --dir-option=4=/opt/my-macwave. Run install.sh --help for the list.

--ci（也可写 --CI）会自动应答目录菜单与许可协议；当选中的目录需要提权时，它要求免密 sudo 或以 root 运行。--dir-option=N 免菜单直接选定第 N 项（Intel 机器为 1-4，Apple 芯片为 1-3）；自定义项要在 = 之后附上路径，例如 --dir-option=4=/opt/my-macwave。完整参数列表可运行 install.sh --help 查看。

Mind where the options go. Writing /bin/bash -c "$(curl ...)" --ci makes --ci the script name ($0), so it is silently dropped; the installer warns when it detects this. The working form puts the options after --.

注意参数的位置。写成 /bin/bash -c "$(curl ...)" --ci 会让 --ci 变成脚本名（$0），从而被静默丢弃；安装器检测到这种用法时会给出警告。正确写法是把参数放在 -- 之后。

uninstall.sh is scriptable in the same way: --force skips the confirmation, which otherwise needs a terminal (use --force in CI):

uninstall.sh 同样支持脚本化调用：--force 跳过确认，而确认本身需要一个终端（因此在 CI 里请使用 --force）：

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/MacWaveOrg/MacWave/HEAD/lib/uninstall.sh)" -- --force

Uninstall MacWave

卸载 MacWave

To completely remove MacWave from your system, run the following command in your terminal:

要从系统中彻底移除 MacWave，请在终端中运行以下命令：

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/MacWaveOrg/MacWave/HEAD/lib/uninstall.sh)"

Download Directory

下载目录

Installed binaries are stored in (options):

已安装的二进制文件存储于（可选）：

1. ~/.local/macwave
2. /opt/macwave
3. /usr/local/macwave (Only Intel Mac)
4. Custom

Config file is stored in (a system-level install always takes priority):

配置文件存储于（系统级安装始终优先）：

1. /opt/macwave_config          system-level install (needs sudo)
2. ~/.config/macwave_config     user-level install (no sudo)

Install Packages

安装软件包

One command downloads, verifies, unpacks and links a package — and checks its SHA256 before anything is installed:

一条命令完成下载、校验、解包与链接，装之前先核对 SHA256：

$ wave install ffmpeg

Not sure of the name? wave search <keyword> searches the index and wave info <package> shows the detail. There is no silent replacement: the version you ask for is the version you get, so pinning is wave install ffmpeg@6.0.

不确定包名？wave search <关键字> 在索引里搜，wave info <包名> 看详情。不会替你换版本 —— 你要哪个就是哪个，需要固定版本就写 wave install ffmpeg@6.0。

Run Packages

运行软件包

Once installed, a package is on your PATH. Just type its name:

装好之后软件包就在 PATH 里，直接敲名字即可：

$ {package_name}

wave install creates that name for you, so there is no extra step. When several versions are installed and you want one of them specifically, add the version:

这条不带版本号的名字是 wave install 一并建好的，无需额外操作。装了多个版本、想指定其中一个时，再带上版本号：

$ {package_name}@{version}

If you installed with --unlink, that name was skipped on purpose — run wave link {package_name} once to bring it back.

如果你当初是用 --unlink 装的，那个名字是特意跳过的 —— 运行一次 wave link {package_name} 就能补回来。

Symlink Management

软链接管理

Since MacWave 2.4, once a versionless link exists, MacWave keeps it pointing at the right version on its own:

从 MacWave 2.4 起，建立不含版本号的软链接后，MacWave 会自动维护它指向的版本：

1. If the highest version is uninstalled, the versionless link moves to the highest version that remains, and the uninstalled version's own link goes with it.
2. An install re-points the versionless link at the version it just installed; add --unlink to that install to skip this.
3. If a package has no versions left at all, the versionless link is removed.
4. A versioned name is always callable, whether or not a versionless link exists.

1. 最高版本被卸载后，不含版本号的软链接会改指向剩余版本中的最高版本，被卸载版本自己的软链接一并撤销。
2. 安装会把不含版本号的软链接指向本次安装的版本；本次安装加上 --unlink 可跳过这一步。
3. 某软件包不再有任何版本时，不含版本号的软链接会被撤销。
4. 无论何种情况，含版本号的名称始终可以调用，即使存在不含版本号的软链接。

A manual wave unlink {package_name} is remembered: a later uninstall will not re-create the link for that package.

手动 wave unlink {package_name} 过的软件包会被记住，之后的卸载不会重新为它建立链接。

Command Reference

命令参考

Usage:
  wave <command> [package] [flags]

Commands:
  install     Install a package (latest version)
  upgrade     Install a package at the latest version
  uninstall   Uninstall a package
  list        List installed packages
  search      Search for a package in the index
  info        Display detailed information about a package
  selfupdate  Update MacWave itself to the latest version
  link        Link installed packages without a version number
  unlink      Remove those unversioned links
  linkquery   Show which version an unversioned link points to
  mirror      Show which addresses packages are fetched from
  latest      Show which packages have a newer version available

Flags:
  -h, --help     Show help for any command
  -V, --version  Print version information
  -v, --verbose  Enable verbose output (show detailed logs)

Global Flags (can be used with any command):
  -s, --silent                  Print nothing at all; the exit code is the signal
                                (beats -v; install / upgrade / uninstall / link /
                                unlink / selfupdate)
  -S, --show-error              With -s, still print the error when a command fails
                                (without the 🌊 prefix, so scripts can parse it)
  -C, --continue                Resume interrupted downloads (like curl -C -)
  --proxy <string>              Specify an HTTP/HTTPS proxy (e.g., http://127.0.0.1:8080)
  --skip-ssl                    Skip SSL certificate verification (insecure)
  --limit-rate <string>         Limit download speed (e.g., 200K, 1M, 5M)
  --max-time <string>           Total time limit for each request (e.g., 40s, 1min, 1min20s, 2h)
  --connect-timeout <string>    Give up if the TCP/TLS handshake takes longer (like curl)
  --content-time <string>       Give up if the server sends nothing for this long
  --ver <string>                Install a specific version (install only; --ver=1.0 works too)
  --install-from-source         Download from the upstream URL instead of MacWave's own store
  --install-python-from-source  Same, for the bundled Python (install / selfupdate)
  MACWAVE_PIP_INDEX             Env var. pip index for the Python deps; default pypi.org/simple

Special Flags:
  wave install <pkgname>@<version>  Download certain version(s) of a package
  wave upgrade <pkgname>            Take a package to the latest version
  wave upgrade --all, -a            Take every installed package to the latest version
      --remove-old-version          Remove versions older than the one just installed
      --remove-old-versions         Same as --remove-old-version
      --rov                         Same as --remove-old-version
      -X                            Same as --remove-old-version
      --unlink                      Leave the unversioned link alone (install / uninstall)
      --all, -a                     Apply to every installed package
                                    (upgrade / link / unlink / linkquery)

Self Update:
wave selfupdate                    Update MacWave itself
wave selfupdate --max-time=2min    Same, but give each request two minutes

Unversioned Links:
wave link <name>                   Link a package to its highest installed version
wave linkquery <name>              Show what <name> is linked to (e.g. 🌊 ffmpeg@9.0)
wave unlink <name>                 Remove that link

Latest Versions:
wave latest <name>                 Show whether a package has a newer version
wave latest --all, -a              Same, for every installed package

Mirror Configuration:
wave mirror                        Show the address each source is fetched from
    --json / --yaml / --toml       Print the same information in that format
    --raw                          Print ready-to-paste export lines
    --only-set                     With --raw: export only the sources you overrode
    --show-password                Print passwords instead of six asterisks
    --hide-user                    Mask the user name too

Uninstalling a version re-points the link to the next highest one, and removes
the link when no version is left. uninstall --unlink keeps the link as-is, and
refuses to run when that would leave the link pointing at the version you are
removing.

Mirrors

镜像站

Officially verified mirror:
https://mirror.repohub.top

官方认证的镜像站：
https://mirror.repohub.top

For Developers

面向开发者

See docs.macwave.org

见 docs.macwave.org

Supported Packages

支持的软件包

(Listed in alphabetical order)

（按字母顺序排列）

atuin            by atuinsh
bat              by David Peter
batt             by charlie0129
btop             by Aristocratos
choma            by opa334
cloc             by Al Danial
delta            by dandavison
dust             by bootandy
eza              by Christina Sørensen and the eza community
fd               by David Peter
ffmpeg           by FFmpeg Team
fileicon         by Michael Klement
fx               by antonmedv
fzf              by Junegunn Choi
htop             by Hisham Muhammad and the htop team
hyperfine        by sharkdp
ipsw             by blacktop
jq               by Stephen Dolan, Nicolas Williams, et al.
ldid             by Jay Freeman (saurik) / Procursus Team
lsd              by Abin Simon
ncdu             by Yoran Heling
ollama           by ollama
palera1n         by palera1n Team
pandoc           by John MacFarlane
rg               by Andrew Gallant
sk               by skim-rs
starship         by starship
taskwarrior-tui  by kdheepak
tmux             by Nicholas Marriott and contributors
tree             by Steve Baker, Thomas Moore, et al.
trollrestore     by JJTech (@JJTech0130)
wget             by GNU Project
yq               by Mike Farah
zoxide           by Ajeet D'Souza

License

许可证

This project is licensed under the MIT License.

本项目基于 MIT 许可证 发布。