grew

README

🥤 grew

A lean, mean, package-managing machine. In Go.

grew is what happens when you look at your package manager and think: "This could be so much simpler." Deterministic installs. Clean symlinks. A doctor that actually tells you what's wrong. No drama.

💬 A word from the author: I've been a die-hard Homebrew user for longer than I care to admit. brew and I? We go way back. Late nights, broken PATH, the works — and I loved every minute of it. I love brew so much, in fact, that I thought: "What if I just… made it better?" Audacious? Absolutely. Foolish? Possibly. Fun? You bet. grew is my love letter to brew — written in Go, with a cheeky grin.

---

✨ What it does

• 📦 Formula + cask installs with SHA256 verification (no funny business)
• 🚰 Tap auto-install — automatically clones missing taps when you request user/repo/formula
• ⚡ Multi-hop binary delta updates — selfupdate uses bspatch to seamlessly apply sequences of intermediate patches to reach the latest version, saving bandwidth, with an automated CI patcher tool for releases and -U upgrade path verification
• 🔐 Dual-hash verification — self-updates and release assets are verified against both SHA256 and SHA512 to prevent single-algorithm collision attacks
• 🔒 Sandboxed source builds using macOS Seatbelt to keep your system safe
• 🔐 Sandboxed post-install scripts — keg is read-only, network denied, minimal env (Homebrew runs these unsandboxed)
• ✍️ Ed25519 bottle signing — cryptographic signatures on downloads, verified against a local trust store
• 🏷️ Signed tap verification — refuse or warn on unsigned git commits in tap repos (HOMEGREW_TAP_VERIFY)
• 📋 Install snapshots — per-file SHA256 manifests (.MANIFEST.json) recorded at install time for integrity verification
• 🧾 Installation receipts — stores build options, dependencies, and provenance metadata (INSTALL_RECEIPT.json) in the keg for future reference
• 📌 Lockfile — pin exact versions, hashes, and dependency trees for reproducible environments
• 🔗 Deterministic linking with opt symlinks and dry-run support (look before you link)
• 🔄 Keg relocation — rewrites hardcoded library paths in bottles at install time via install_name_tool, so binaries just work without DYLD_LIBRARY_PATH hacks
• 🌳 Dependency resolver with an optional tree view (for the visually inclined)
• 🩺 Doctor that checks perms, HTTPS, broken links, snapshot integrity, stale kegs, and cask notarization
• 🛡️ Hardened command execution — -- end-of-options on all external commands, shell-free namespace setup with positional parameters, XML-safe plist generation
• 🧱 Zip Slip protection — archive extraction validates symlink indirection to prevent writes outside the destination
• 🔍 Vulnerability scanning — queries OSV.dev for known CVEs via the vuln-scan command
• 🛡️ macOS Quarantine — automatically applies com.apple.quarantine attributes to downloaded apps and binaries, ensuring Gatekeeper protection is active
• 🪵 Structured logging via log/slog with CLI-friendly output (DEBUG/INFO/WARN/ERROR levels, -v/-d/-q flags). Debug logs include source file and line number context.
• 🎨 Colorful output — ANSI-colored output with automatic TTY detection for a polished, Homebrew-like aesthetic.
• 🐚 Alias + shellenv helpers so your workflows stay snappy (i, rm, ls, up, ug, dr)

---

🚀 Getting Started

Get Grew

Download the latest release for your platform from the Releases page, extract it, and run setup:

tar -xzf grew_*.tar.gz
./grew setup

Build from source

Prerequisites: Go 1.26+, git, and a dream.

git clone https://github.com/homegrew/grew.git
cd grew
make build          # or: go generate ./internal/... && go build -o grew

Set up the prefix

grew needs a home — a directory tree for the Cellar, symlinks, taps, and config. The setup command creates it and copies the binary into place:

./grew setup   # macOS ARM → /opt/homegrew, Intel → /usr/local/homegrew

The system prefix isolates sandboxed builds from $HOME, preventing them from reaching ~/.ssh, ~/.gnupg, or other sensitive dotfiles. After setup, ownership is transferred to your user — no root needed at runtime.

Wire up your shell

Add this to your shell profile so grew-installed binaries and libraries are available:

# bash (~/.bashrc) or zsh (~/.zshrc)
eval "$(grew shellenv)"

# fish (~/.config/fish/config.fish)
grew shellenv fish | source

Install something

grew i jq                   # 'i' is an alias for 'install'
grew install --cask firefox

That's it. No dark rituals. No 47-step setup guide.

---

🗑️ Uninstallation

grew stores most of its data in its prefix directory, but some items (like Cask applications and background services) are linked to system directories. To completely remove grew and all of its traces:

1. Clean up installed packages (Casks and Services):

Uninstall casks and stop services first so grew can clean up /Applications and your service managers (launchd/systemd):

# Stop and remove all background services
for s in $(grew services ls | awk 'NR>1 {print $1}'); do grew services stop $s; done

# Uninstall all macOS casks
for c in $(grew list --cask | awk '{print $1}'); do grew uninstall --cask $c; done

2. Delete the prefix directory:

• macOS (Apple Silicon):

  sudo rm -rf /opt/homegrew
  

• macOS (Intel):

  sudo rm -rf /usr/local/homegrew
  

• Devmode (User-local install via --unsafe):

  rm -rf ~/.homegrew
  

3. Clean up your shell profile:

Open your shell configuration file (e.g., ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish) and remove the line that initializes grew:

# Remove this line:
eval "$(/opt/homegrew/bin/grew shellenv)"

Restart your terminal, and grew is completely gone.

---

📖 Usage

For an in-depth look at how grew installs itself, its self-update mechanism, and the developer mode, check out the Architecture & Technical Details.

grew i jq nmap               # install multiple formulas (alias 'i')
grew install --force jq      # force reinstall even if already installed
grew install -s ldns         # build from source, like a purist
grew install --cask firefox  # going big
grew link jq                 # stitch it in
grew deps --tree jq          # what hath jq wrought
grew up                      # stay fresh (alias 'up' for update)
grew ug                      # upgrade all (alias 'ug')
grew version                 # what are we running
grew autoremove --dry-run    # see which orphaned dependencies would be removed
grew autoremove              # clean up unused dependencies
grew rm --force jq           # uninstall even if not installed (alias 'rm')
grew cleanup -n              # peek before you sweep
grew cleanup --scrub         # aggressive cache cleaning
grew cleanup --prune=7       # remove cache older than a week
grew verify jq               # check installed files against manifest
grew vuln-scan -q            # scan for CVEs and only show critical/high severity findings
grew lock                    # pin your environment
grew audit --strict          # lint your formulas
grew cache                   # show download cache
grew cache jq                # show cache path for jq
grew cache --os=darwin jq    # show cache path for a different OS
grew leaves -r | xargs grew uninstall # uninstall all top-level packages installed on request

---

🗺️ Commands

Command	What it does
install, i	Install formulas or casks (-f to force, -s to build from source)
uninstall, rm	Send formulas or casks to the void (-f to ignore missing or errors, delete all versions)
autoremove	Uninstall formulae that were only installed as a dependency and are no longer needed (--dry-run supported)
list, ls	See what you've collected
leaves [-r] [-p]	List installed formulas that are not dependencies of another installed formula
info	Stalk packages
search	Find the thing
link	Weave formulas into your PATH
unlink	Cut the thread
update, up	Refresh tap definitions
upgrade, ug	Get the new hotness
outdated	The hall of shame
reinstall	Uninstall + install from scratch (--cask, -f without checking for previously installed keg-only or non-migrated versions)
cleanup	Remove old versions and prune download cache (-s to scrub all, --prune=DAYS)
deps	Dependency spelunking
alias	Name things your way
audit	Lint formula/cask definitions for quality and security
lock	Generate, check, or show a reproducible lockfile
verify	Check installed packages against their snapshot manifests
sign	Sign formula SHA256 hashes with an Ed25519 key
services	Manage background services (start, stop, restart, list)
setup	One-time prefix setup
doctor, dr	It's not a bug, it's a misconfiguration
vuln-scan	Scan installed packages for security vulnerabilities
config	What grew thinks it knows
shellenv	Wire up your shell
pin / unpin	Freeze formulas to prevent upgrades
completion	Generate shell completion (bash, zsh, fish)
cache	Display download cache root or specific package cache paths (alias --cache)
version	Print version and exit
help	You got this

---

⚙️ Configuration

grew keeps its stuff tidy under one roof. Tweak it with env vars:

Variable	Default	What it is
HOMEGREW_PREFIX	(inferred from binary location)	Root of the grew tree
HOMEGREW_APPDIR	/Applications	Where casks live
HOMEGREW_TAP_VERIFY	off	Tap commit signature policy (off, warn, strict)
HOMEGREW_ALLOWED_HOSTS	(built-in allowlist)	Additional hosts for SSRF-protected downloads
HOMEGREW_CLEANUP_MAX_AGE_DAYS	120	Max age in days for cached downloads

Everything else flows from the prefix:

/opt/homegrew/              (or /usr/local/homegrew on Intel)
├── Cellar/        ← installed packages (each keg has a .MANIFEST.json)
├── Taps/          ← formula definitions (git-cloned or API-fetched)
├── bin/           ← symlinked binaries
├── lib/           ← symlinked libraries
├── include/       ← symlinked headers
├── opt/           ← per-formula keg symlinks
├── etc/           ← trusted-keys (Ed25519 public keys, one per line)
├── tmp/           ← ephemeral stuff
├── var/log/       ← audit log
└── grew.lock      ← lockfile (opt-in, created by `grew lock`)

---

🛠️ Development

make test-unit     # run unit tests
make test-smoke    # run quick health checks
make test-integration # run command-level integration tests
make test-e2e      # run full lifecycle E2E tests (takes several minutes)
make check-all     # run all of the above
make dev           # build with 'devmode' tag enabled

Developer mode

Release builds will prompt for elevated privileges to setup the system prefix. For local development you can build with the devmode tag and pass --unsafe to setup to install to ~/.homegrew without root:

make dev
./grew setup --unsafe    # installs to ~/.homegrew as your user
./grew install jq        # works without root

Both gates are required — the build tag compiles in the code path, and --unsafe activates it at setup time. Release binaries ignore --unsafe entirely.

Project layout

grew/
├── cmd/              ← standalone command packages (install, upgrade, etc.)
├── internal/
│   ├── auditlog/     ← persistent record of all install/upgrade/tap actions
│   ├── bpatch/       ← binary delta patching (using bspatch)
│   ├── cache/        ← download cache management and pruning
│   ├── cask/         ← cask parsing, Caskroom, and helpers
│   ├── cellar/       ← installed package management and cleanup
│   ├── cli/          ← shared CLI initialization and command registration
│   ├── cmd/          ← legacy command bridge and high-level orchestration
│   ├── depgraph/     ← dependency resolution (Kahn's toposort)
│   ├── downloader/   ← HTTP download + SHA256/512 + archive extraction
│   ├── flags/        ← global CLI flags (-v, -d, -q)
│   ├── formula/      ← formula parsing and dependency gathering
│   ├── fsutil/       ← filesystem utilities (DiskUsage, PruneEmptyDirs, Lock)
│   ├── homebrew/     ← Homebrew JSON API client and compatibility logic
│   ├── installer/    ← core installation logic (formula, cask, self-update)
│   ├── linkage/      ← dynamic library linkage analysis
│   ├── linker/       ← deterministic symlink management
│   ├── lockfile/     ← reproducible environment pinning
│   ├── osvdev/       ← OSV.dev API client for vulnerability scanning
│   ├── quarantine/   ← macOS quarantine attribute and Trash management
│   ├── receipt/      ← installation receipt management
│   ├── release/      ← grew release management and download helpers
│   ├── relocation/   ← keg relocation (rewrite dylib/ELF paths)
│   ├── runtime/      ← runtime environment (root detection, prefix, devmode gate)
│   ├── sandbox/      ← build + post-install sandboxing (macOS Seatbelt)
│   ├── service/      ← background service management
│   ├── signing/      ← Ed25519 bottle signing + trust store
│   ├── sudo/         ← secure privilege escalation handling
│   ├── tap/          ← tap repo management + commit verification
│   └── version/      ← embedded version and helpers
├── pkg/
│   ├── config/       ← prefix and path resolution
│   ├── context/      ← unified execution context (Context, InstallContext)
│   ├── doctor/       ← diagnostic engine and checks
│   ├── logger/       ← CLI-friendly log/slog handler with source context
│   ├── safepath/     ← safe path manipulation and normalization
│   ├── snapshot/     ← per-file manifest capture + integrity verification
│   ├── ui/           ← zero-dependency ANSI color and TTY detection
│   └── validation/   ← name/version/SHA256/path validation
├── tests/
│   ├── integration/  ← command-level integration tests
│   ├── smoke/        ← quick health checks
│   ├── e2e/          ← full lifecycle end-to-end tests
│   ├── testbin/      ← test proxy binary source
│   └── testhelper/   ← shared test utilities
├── root.go           ← Root CLI command definition (Grew)
├── main.go           ← CLI entry point
└── tools/            ← genrepo (converter), patcher (delta patch generator)

---

🔐 Security Model

grew is designed to be more secure than Homebrew out of the box:

Feature	grew	Homebrew
Bottle signing	Ed25519 signatures verified against local trust store	None — relies on HTTPS + SHA256 only
Tap verification	Optional GPG/SSH commit signature enforcement	None
Post-install sandbox	Read-only keg, no network, minimal env	Unsandboxed
Source build sandbox	macOS Seatbelt, no network	macOS Seatbelt only
Install manifests	Per-file SHA256 snapshot (.MANIFEST.json) at install time	None
Installation receipts	Provenance and dependency metadata (INSTALL_RECEIPT.json) stored alongside the manifest	Metadata stored in INSTALL_RECEIPT.json
Lockfile	Full dependency tree with hashes	None
Integrity check	grew verify + grew doctor snapshot check	None
Dual-hash verification	Self-updates and release assets use both SHA256 and SHA512	None
Self-update health check	Patched binaries are execution-tested in a sandbox before replacement	None
HTTPS enforcement	At parse time — HTTP URLs rejected before download	At download time
Path traversal protection	Validated at cellar, linker, loader, and archive extraction layers	Partial
Shell injection prevention	Namespace setup uses positional parameters to eliminate injection risks; systemd ExecStart and launchd plist values properly escaped	N/A
Zip Slip protection	Symlink indirection attacks blocked during tar/zip extraction	Partial
Command argument hardening	-- end-of-options separator on all external commands (git, systemctl, launchctl, hdiutil, tar, etc.)	Not consistently applied
macOS Quarantine	Apply() via LaunchServices for all downloads	None
Vulnerability scanning	Integrated vuln-scan powered by OSV.dev	Requires external gems/tools

Gradual rollout: signature verification doesn't block installs until you add keys to etc/trusted-keys. Tap verification is opt-in via HOMEGREW_TAP_VERIFY. This lets you adopt security features incrementally.

---

🗺️ Roadmap

Got ideas? Bugs? Grievances? → Open an issue

Hot takes on the list:

• Build vs Runtime Dependency distinction
• SLSA provenance attestations for bottles
• Content-addressable bottle storage
• Windows support (one day, probably, maybe)

---

🤝 Contributing

1. Fork it
2. Branch it (git checkout -b feature/your-cool-thing)
3. Commit it (git commit -m "Add the cool thing")
4. Push it (git push origin feature/your-cool-thing)
5. PR it

PRs welcome. Drama not so much.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

📬 Contact

• 🐛 Open an issue
• 🔗 Project on GitHub

---

💛 Acknowledgments

• Best-README-Template — the scaffold beneath the scaffold
• Everyone who ever squinted at a wall of package manager output and thought "there has to be a better way"

Documentation

Overview

Command grew is the entry point for the grew package manager.