Manage Homebrew packages¶

Packages are declared in Brewfiles and installed with brew bundle. The core file applies to every machine; profile overlays layer GUI and work-only packages on top.

The three Brewfiles¶

Brewfile — core CLI formulae for all profiles. Keep GUI/cask entries out of this file.
Brewfile.personal — GUI casks, fonts, and apps for profiles with a desktop (personal, work). Skipped on minimal/server.
Brewfile.work — work-only additions, layered on top for the work profile.

bootstrap.sh installs the core file plus the active profile's overlays (see Profiles). The same list drives verify.sh's Brewfile-drift check.

Add a package¶

Pick the right file for its scope, then add a line. Use brew "<formula>" for CLI tools and cask "<app>" for GUI apps.

# Brewfile (core CLI — every machine)
brew "htop"            # short comment explaining the tool

# Brewfile.personal (GUI app — desktop profiles)
cask "obsidian"

# Brewfile.work (work-only tool)
brew "awscli"

Install it:

brew bundle --file=~/dotfiles/Brewfile            # core
brew bundle --file=~/dotfiles/Brewfile.personal   # GUI overlay
brew bundle --file=~/dotfiles/Brewfile.work       # work overlay

brew bundle is idempotent — it installs only what's missing, so it's safe to re-run.

Remove a package¶

Delete its line from the Brewfile, then uninstall it from the machine (editing the file alone does not remove an installed package):

brew uninstall htop

To prune everything not listed in a Brewfile, use cleanup (review the dry run first):

brew bundle cleanup --file=~/dotfiles/Brewfile            # preview removals
brew bundle cleanup --file=~/dotfiles/Brewfile --force    # actually remove

Check for drift¶

brew bundle check reports whether everything in a Brewfile is installed:

brew bundle check --file=~/dotfiles/Brewfile

update.sh and verify.sh already iterate the active profile's Brewfiles, so a routine bash ~/dotfiles/update.sh keeps installed packages in sync.

Commit¶

git -C ~/dotfiles add Brewfile Brewfile.personal Brewfile.work
git -C ~/dotfiles commit -m "feat: add htop to core Brewfile"

Tip

Put a tool in the lowest scope that needs it. A CLI used on every machine belongs in Brewfile; a desktop app belongs in Brewfile.personal; keep work-only tooling in Brewfile.work so personal machines stay lean.