CHANGELOG Copy Section

Changelog

All notable changes to zerobrew will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[Unreleased] Copy Chapter

Changed Copy Section

Fixed Copy Section

[0.3.2] - 2026-06-11 Copy Chapter

Security Copy Section

[0.3.1] - 2026-05-30 Copy Chapter

Fixed Copy Section

Changed Copy Section

[0.3.0] - 2026-05-29 Copy Chapter

Added Copy Section

Fixed Copy Section

Changed Copy Section

[0.2.1] - 2026-03-14 Copy Chapter

Fixed Copy Section

[0.2.0] - 2026-03-12 Copy Chapter

Added Copy Section

Fixed Copy Section

Changed Copy Section

[0.1.2] - 2026-02-15 Copy Chapter

Added Copy Section

Fixed Copy Section

Changed Copy Section

[0.1.1] - 2026-02-08 Copy Chapter

Initial release of zerobrew - a fast, modern package manager. We're excited for our pilot release and
want to thank all of the support from all channels, as well as all of our contributors up to this point.

To get an idea of the initial features zerobrew supports, take a look at the README.

See the full commit history for more details.

[Unreleased]: https://github.com/lucasgelfond/zerobrew/compare/v0.3.2...HEAD
[0.3.2]: https://github.com/lucasgelfond/zerobrew/compare/v0.3.1...v0.3.2
[0.3.1]: https://github.com/lucasgelfond/zerobrew/compare/v0.3.0...v0.3.1
[0.3.0]: https://github.com/lucasgelfond/zerobrew/compare/v0.2.1...v0.3.0
[0.2.1]: https://github.com/lucasgelfond/zerobrew/compare/v0.2.0...v0.2.1
[0.2.0]: https://github.com/lucasgelfond/zerobrew/compare/v0.1.2...v0.2.0
[0.1.2]: https://github.com/lucasgelfond/zerobrew/compare/v0.1.1...v0.1.2
[0.1.1]: https://github.com/lucasgelfond/zerobrew/releases/tag/v0.1.1

---

CONTRIBUTING Copy Section

Contributing to zerobrew

Thanks for your interest in contributing to zerobrew! This document provides guidelines for contributing to the project.

Licensing Copy Chapter

By contributing to zerobrew, you agree your contributions will be dual-licensed under either Apache OR MIT, at the licensee's choice.

Soft Prerequisites Copy Chapter

- Rust 1.90 or later
- Access to either a macOS or Linux machine

A note on LLM usage Copy Chapter

_Please understand_ that we reserve the right to simply close your PR if it exhibits clear indicators
of heavy LLM usage. We understand you are excited to contribute but the code must reach a level of quality
that's typically achieved through thoughtful engagement in the community and the issues/agenda of zerobrew- NOT
by throwing a prompt into an LLM and opening a PR with no direction.

If you ever need help or want to walk through an issue or idea that you have with one of the maintainers, feel free to join
the community discord; we would be more than happy to assist you.

Project Structure Copy Chapter

zerobrew is organized as a Cargo workspace with three crates:

- zb_core: Core data models and domain logic (formula resolution, bottle selection)
- zb_io: I/O operations (API client, downloads, extraction, installation)
- zb_cli: Command-line interface

Any changes you make that touch several crates should be organized properly. See commit hygiene

General Development Workflow Copy Chapter

We prefer that a PR is linked to an open issue or previously discussed through other channels.
If you are introducing changes that aren't otherwise reported or tracking please either reach
out in the Discord to give us a heads up or open an issue first to discuss your changes.

General flow:
1. Fork the repo
2. Make your changes and ensure, at the _least_:
- Code is formatted: cargo fmt --all
- No clippy warnings: cargo clippy --workspace --all-targets -- -D warnings
- Unit tests pass: cargo test --workspace
- Integration tests pass: cargo test --workspace -- --ignored (or just test for all tests)

turnaround!

Using Just Copy Section

This project includes a Justfile, Install just and use these commands instead of cargo (for ease of development):

- just build Check formatting, lint, then build the binary (Builds debug binary)
- just install Build and install zb to $HOME/.local/bin (Customizable with $ZEROBREW_BIN)
- just uninstall Remove all zerobrew installations and configurations
- just fmt Format code with rustfmt
- just fmt-check Check code formatting
- just lint Run clippy with strict warnings
- just test Run all workspace tests (unit & integration)

Before creating a PR make sure you build your changes and test them.

3. Write tests for new functionality. Each module should have accompanying tests.
4. Commit your changes with clear, descriptive commit messages (see below)
5. Push to your fork and submit a pull request.

Commit hygiene Copy Chapter

fix / feat: description

for instance:

fix(zb_cli): foo bar moo baz

fix      # -> fixes a bug or regression
feat     # -> new feature
chore    # -> housekeeping (deps, typos in docs, etc.)
tests    # -> added, changed or removed tests
ci       # -> changes to ci
refactor # -> refactored code
perf     # -> performance related
build    # -> changes to build system (i.e. ext deps, tooling, scripts, etc)

Generally speaking, we also ask that you please write isolated, atomic commits.
This means if you are approaching a PR that touches various parts of the codebase for example, ensure that your commits
are contained and cleanly seperated, properly describing/notating which commits belong where.

Testing Copy Chapter

- Unit tests should be colocated with the code in mod tests blocks
- Use tempfile for filesystem tests
- Use wiremock for HTTP mocking in integration tests
- Tests should be deterministic and not rely on external network access

Running Benchmarks Copy Chapter

To benchmark performance:

just bench --full

This runs a 100-package installation suite comparing zerobrew to Homebrew. This is especially crucial to run if you are
planning on contributing to performance/optimization related changes.

Useful options:

just bench --quick
just bench --dry-run
just bench --full results/
just bench --format csv --output benchmark.csv
just bench --log bench.log

Notes:
- Defaults to the quick package list (22 packages); use --full for all 100.
- --full [dir] writes all formats (txt/json/csv/html) to the directory.
- --output infers format from file extension when --format is omitted.
- Output includes cold + warm cache speedups per package.

macOS Homebrew permissions Copy Section

On macOS, Homebrew should be installed with a user-writable prefix. If just bench fails with a permission error, fix it by running:

sudo chown -R "$(whoami)" "$(brew --prefix)"

Questions? Copy Chapter

For further questions, open an issue on GitHub.

---

README Copy Section

<div align="center">

<h2>zerobrew</h2>

<p align="center">
<strong>English</strong> ·
<a href="README.zh.md">中文</a>
</p>

[](https://github.com/lucasgelfond/zerobrew/actions/workflows/ci.yml)
[](https://github.com/lucasgelfond/zerobrew/actions/workflows/test.yml)
[](https://github.com/lucasgelfond/zerobrew/releases)
[](https://discord.gg/ZaPYwm9zaw)
[](./LICENSE-MIT.md)
[](./LICENSE-APACHE.md)

<img alt="zerobrew demo" src="./assets/zb-demo.gif" />

<p><strong>zerobrew brings uv-style architecture to Homebrew packages on macOS and Linux.</strong></p>

</div>

Install Copy Chapter

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

The installer updates your shell config. After it finishes, restart your terminal
or run the source command it prints.

Or via Homebrew:

brew install lucasgelfond/zerobrew/zerobrew

Update zerobrew Copy Chapter

If you used the standalone installer, rerun it:

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

If you installed with Homebrew:

brew update && brew upgrade zerobrew

Quick start Copy Chapter

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

Performance snapshot Copy Chapter

<div align="center">

| Package | Homebrew | ZB (cold) | ZB (warm) | Cold Speedup | Warm Speedup |
|---------|----------|-----------|-----------|--------------|--------------|
| Overall (top 100) | 452s | 226s | 59s | 2.0x | 7.6x |
| ffmpeg | 3034ms | 3481ms | 688ms | 0.9x | 4.4x |
| libsodium | 2353ms | 392ms | 130ms | 6.0x | 18.1x |
| sqlite | 2876ms | 625ms | 159ms | 4.6x | 18.1x |
| tesseract | 18950ms | 5536ms | 643ms | 3.4x | 29.5x |

</div>

Relationship with Homebrew Copy Chapter

zerobrew is more of a performance-optimized client for the Homebrew ecosystem. We rely on:
- Homebrew's formula definitions (homebrew-core)
- Homebrew's pre-built bottles when available
- Homebrew's package metadata and infrastructure

Our innovations focus on:
- Content-addressable storage for deduplication
- APFS clonefiles for zero-overhead copying
- Source build fallback using Homebrew's Ruby DSL

zerobrew is experimental. We recommend running it alongside Homebrew rather than as a replacement, and do _not_
recommend purging homebrew and replacing it with zerobrew unless you are absolutely sure about the implications of
doing so.

Project status Copy Chapter

<div align="center">
<a href="https://star-history.com/#lucasgelfond/zerobrew&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=lucasgelfond/zerobrew&type=Date&theme=dark" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=lucasgelfond/zerobrew&type=Date" />
</picture>
</a>
</div>

- Status: Experimental, but already useful for many common Homebrew formulas.
- Feedback: If you hit incompatibilities, please open an issue or PR.
- License: Dual-licensed under Apache 2.0 OR MIT, at your choice.

---

SECURITY Copy Section

Security Policy

Supported Versions Copy Chapter

We take security seriously and provide security updates for the latest version zerobrew.
We strongly recommend keeping your zerobrew dependencies up to date.

Reporting a Vulnerability Copy Chapter

Please do not report security vulnerabilities through public GitHub issues.

If you discover a security vulnerability in nmrs or any of the related crates, please report it privately by emailing
lucas.gelfondATgmail.com.

Please include the following information in your report:

- A clear description of the vulnerability
- Steps to reproduce the issue
- Potential impact and attack scenarios
- Any suggested fixes or mitigations
- Your contact information for follow-up questions

What constitutes a security vulnerability? Copy Section

For zerobrew, security vulnerabilities may include but are not limited to:

- Package substitution: Ability to install malicious packages by manipulating formula resolution or tap priority
- Privilege escalation: Unauthorized access to system directories or operations that should require elevated permissions
- Credential exposure: Leaking API tokens, tap credentials, or other sensitive data through logs, errors, or memory
- Path traversal: Malicious bottle archives that could write files outside the intended cellar/store directories
- Denial of service: Crashes, hangs, or resource exhaustion that prevent legitimate package management
- Information disclosure: Exposing installed packages, store paths, or system configuration to unauthorized processes
- Input validation failures: Improper handling of malformed formula names, tap references, or bottle data leading to undefined behavior
- Race conditions: Timing vulnerabilities in concurrent downloads, extraction, or linking that could lead to security issues
- Checksum bypass: Ability to install packages without proper SHA256 verification or with manipulated checksums
- Symlink attacks: Malicious symlinks in bottles that could overwrite system files during materialization or linking
- Dependency confusion: Installing malicious packages by exploiting tap resolution order or dependency specifications
- Supply chain attacks: Compromised taps or formula sources serving backdoored bottles
- Arbitrary code execution: Malicious bottles containing executables that run with user privileges during installation
- Dependency vulnerabilities: Security issues in upstream crates (reqwest, tokio, tar, etc.) that affect zerobrew

For the CLI specifically:
- Command injection: Malicious formula names or tap references that could execute unintended shell commands
- File system access: Unauthorized reading or writing of files outside the intended root/prefix directories

Response Timeline Copy Chapter

We are committed to responding to security reports promptly:

- Acknowledgment: We will acknowledge receipt of your vulnerability report within
24 hours
- Initial assessment: We will provide an initial assessment of the report within
5 business days
- Regular updates: We will provide progress updates at least every 7 days until
resolution
- Resolution: We aim to provide a fix or mitigation within 30 days for critical
vulnerabilities

Response times may vary based on the complexity of the issue and availability of maintainers.

Disclosure Policy Copy Chapter

We follow a coordinated disclosure process:

1. Private disclosure: We will work with you to understand and validate the vulnerability
2. Fix development: We will develop and test a fix in a private repository if necessary
3. Coordinated release: We will coordinate the public disclosure with the release of a fix
4. Public disclosure: After a fix is available, we will publish a security advisory

We request that you:
- Give us reasonable time to address the vulnerability before making it public
- Avoid accessing or modifying data beyond what is necessary to demonstrate the vulnerability
- Act in good faith and avoid privacy violations or destructive behavior

Security Advisories Copy Chapter

Published security advisories will be available through:

- GitHub Security Advisories on the
zerobrew repository
- RustSec Advisory Database
- Release notes and changelog entries

Recognition Copy Chapter

We appreciate the security research community's efforts to improve the security of zerobrew. With
your permission, we will acknowledge your contribution in:

- Security advisories
- Release notes
- Project documentation

If you prefer to remain anonymous, please let us know in your report.

Scope Copy Chapter

This security policy covers zerobrew wholly.

Additional Resources Copy Chapter

- Contributing Guidelines
- Code of Conduct
- Rust Security Policy

Thank you for helping to keep zerobrew and the Rust ecosystem secure!

---