DOCSEARCHbyAlgolia
Submit Docs

zerobrew Documentation

repository·main·Indexed 27 days ago

https://github.com/lucasgelfond/zerobrew

A performance-optimized client for the Homebrew ecosystem on macOS and Linux. zerobrew introduces uv-style architecture, utilizing content-addressable storage and APFS clonefiles for deduplication and zero-overhead copying. It works alongside Homebrew by leveraging homebrew-core formula definitions and pre-built bottles, providing a CLI (zb and zbx) for package installation, Brewfile bundle management, and system maintenance.

Tokens
10.6K
Snippets
13
Records
90
Agent score
90%

What's inside zerobrew

  1. Understand the relationship between zerobrew and Homebrew

    main

    zerobrew is a performance-optimized client for the Homebrew ecosystem. It is experimental and designed to be run alongside Homebrew rather than as a total replacement.

    How it works:

    • It relies on Homebrew's formula definitions (homebrew-core), pre-built bottles, and package metadata.
    • It introduces optimizations like content-addressable storage for deduplication and APFS clonefiles for zero-overhead copying.
    • It falls back to source builds using Homebrew's Ruby DSL.

    Warning: Do not purge Homebrew and replace it with zerobrew unless you are certain of the implications.

  2. Install zerobrew

    main

    You can install zerobrew using a standalone installation script or via Homebrew.

    Using the installation script: Run the following command to download and install. The installer will update your shell configuration. After installation, restart your terminal or run the source command provided by the installer output.

    Using Homebrew:

    brew install lucasgelfond/zerobrew/zerobrew
    curl -fsSL https://zerobrew.rs/install | bash

  3. Update zerobrew

    main

    Depending on your installation method, use one of the following commands to update the zb binary:

    If installed via the standalone script: Re-run the installation script:

    curl -fsSL https://zerobrew.rs/install | bash

    If installed via Homebrew:

    brew update && brew upgrade zerobrew

    Note: The commands zb update (refreshes package metadata) and zb upgrade (upgrades packages installed via zerobrew) do not update the zb binary itself.

  4. Quick start with zerobrew CLI

    main

    Use the zb command to manage Homebrew packages with high performance. Common tasks include:

    • Installing packages: zb install <package> or zb install <pkg1> <pkg2>.
    • Bundle management: Use zb bundle to install from a Brewfile, zb bundle dump to export installed packages to a Brewfile, or zb bundle install -f <file> for custom files.
    • Upgrading/Updating: zb outdated lists packages with new versions, zb upgrade upgrades all outdated packages, and zb upgrade <package> upgrades specific ones.
    • Maintenance: zb uninstall <package> removes a package, zb reset uninstalls everything, and zb gc performs garbage collection on unused storage entries.
    • Running without linking: Use zbx <package> <command> to run a package without linking it to your system.

    Example usage:

    zb install jq
zb bundle dump
zb upgrade

  5. Use zerobrew CLI commands

    main

    zerobrew (aliased as zb or zbx) provides a suite of commands for managing Homebrew packages with high performance using content-addressable storage and APFS clonefiles.

    Package Management

    • zb install <package>: Install one or more packages.
    • zb uninstall <package>: Uninstall a package.
    • zb outdated: List packages that have newer versions available.
    • zb upgrade: Upgrade all outdated packages.
    • zb upgrade <package>: Upgrade specific packages.
    • zb reset: Uninstall everything.
    • zb gc: Garbage collect unused store entries.

    Bundle Management

    • zb bundle: Install packages listed in a Brewfile.
    • zb bundle install -f <file>: Install from a custom file.
    • zb bundle dump: Export currently installed packages to a Brewfile.
    • zb bundle dump -f <file> --force: Export to a custom file, overwriting if it exists.

    Execution

    • zbx <command> --version: Run a command (like --version) without linking the package to your path.
    zb install jq                   # install one package
zb install wget git             # install multiple
zb bundle                       # install from Brewfile
zb bundle install -f myfile     # install from custom file
zb bundle dump                  # export installed packages to Brewfile
zb bundle dump -f out --force   # dump to custom file (overwrite)
zb uninstall jq                 # uninstall one package
zb outdated                     # list packages with newer versions
zb upgrade                      # upgrade all outdated packages
zb upgrade jq wget              # upgrade specific packages
zb reset                        # uninstall everything
zb gc                           # garbage collect unused store entries
zbx jq --version                # run without linking

  6. Configure shell environment for zerobrew

    main

    During initialization, zerobrew attempts to automatically add required environment variables and paths to your shell configuration file. It supports the following shells:

    • zsh: Writes to .zshenv (if exists) or .zshrc (or $ZDOTDIR/.zshrc).
    • bash: Writes to .bash_profile (if exists) or .bashrc.
    • fish: Writes to ~/.config/fish/conf.d/zerobrew.fish.
    • other POSIX shells: Writes to ~/.profile.

    Environment Variables Managed:

    • ZEROBREW_DIR: The directory where zerobrew internal data is stored.
    • ZEROBREW_BIN: The directory containing zerobrew binaries.
    • ZEROBREW_ROOT: The root directory for zerobrew.
    • ZEROBREW_PREFIX: The prefix directory for installed packages.
    • PKG_CONFIG_PATH: Updated to include $ZEROBREW_PREFIX/lib/pkgconfig.
    • CURL_CA_BUNDLE / SSL_CERT_FILE / SSL_CERT_DIR: Automatically configured if ca-certificates is installed within the zerobrew prefix.

    If you use the --no-modify-path flag during initialization, zerobrew will skip writing to your shell config and instead print the manual export commands for you to run.

  7. Initialize zerobrew

    main

    Zerobrew requires initialization to create necessary directories and configure your shell environment. The initialization process creates a root directory (for internal data like cache, db, and locks) and a prefix directory (for installed packages).

    If the directories are not writable, the process will attempt to use sudo to create them and set ownership to the current user.

    macOS Note: On macOS, the chosen prefix must not exceed 13 characters (e.g., /opt/homebrew) because paths inside Mach-O binaries are fixed-size. If your prefix is too long, path-sensitive packages like git or curl will fail to install.

  9. Customize UiTheme with styles and symbols

    main

    You can customize the visual appearance of the Ui by providing a custom UiTheme. A theme consists of UiStyles (using console::Style for colors/formatting) and UiSymbols (the actual string characters used for labels and icons).

    UiStyles Fields:

    • heading_prefix
    • note_label
    • info_label
    • warn_label
    • error_label
    • bullet
    • step_pending
    • step_ok
    • step_fail

    UiSymbols Fields:

    • heading_prefix
    • note_label
    • info_label
    • warn_label
    • error_label
    • bullet
    • step_pending
    • step_ok
    • step_fail

  10. Configure the zerobrew prefix path

    main

    The prefix path (where packages are installed) is determined by:

    1. An explicitly provided cli_prefix path.
    2. The ZEROBREW_PREFIX environment variable.
    3. OS-specific defaults based on the root path:
      • macOS: The root path itself.
      • Other OSs: The root path joined with prefix (e.g., $ROOT/prefix).
    pub fn get_prefix_path(cli_prefix: Option<PathBuf>, root: &Path) -> PathBuf

  11. Configure the zerobrew root path

    main

    The root directory for zerobrew can be determined using the following priority:

    1. An explicitly provided cli_root path.
    2. The ZEROBREW_ROOT environment variable.
    3. The legacy path /opt/zerobrew (if it exists).
    4. OS-specific defaults:
      • macOS: /opt/zerobrew.
      • Other OSs: The XDG_DATA_HOME directory joined with zerobrew. If XDG_DATA_HOME is not set, it defaults to $HOME/.local/share/zerobrew.
    pub fn get_root_path(cli_root: Option<PathBuf>) -> PathBuf

  12. Configure the runtime prefix via `ZEROBREW_PREFIX`

    main
    You can control how zerobrew detects the runtime prefix (used for locating CA bundles and library paths) by setting the ZEROBREW_PREFIX environment variable. If this variable is set, zerobrew will use it as the base path for runtime configuration instead of attempting to detect the prefix from the binary's path or the Cellar directory structure.