Mac OS - Brewfile#

Daily Sync Shortcuts (Keep Computers Mirrored):

  • Run pushbrew on the machine where you just installed/removed software to scan your system, update the Brewfile, and push it to GitHub.
  • Run pullbrew on your other workstations to pull the update and automatically install/clean up your packages to match.

Quick Restore & Sync (Workstation Rebuild):

  • To Restore (New Computer):
    1. Install Homebrew (if missing): /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    2. Clone scripts: git clone git@github.com:marcoue/Scripts.git ~/Scripts
    3. Reinstall all software: brew bundle --file=~/Scripts/MacOS/Brew/Brewfile
  • To Sync Updates (Ongoing):
    • Pull latest and clean up local packages: pullbrew

Related Recovery Guides: Master Checklist: Mac OS - Recovery | Shortcut Configuration: Mac OS - Aliases Management | Repository Standard: Scripts Mangement.

1. Overview & Sync Architecture#

The Homebrew Brewfile standard allows you to declare, version control, and synchronize your entire macOS application environment (command-line tools, GUI applications, and VS Code extensions) across multiple Macs.

1.1 The Synchronized Flow#

  1. Master Configuration: A Brewfile is stored in your central ~/Scripts repository on GitHub (under MacOS/Brew/).
  2. Automated Tracking: A daily background task on the primary workstation checks for package changes, updates the local Brewfile, and pushes updates to GitHub.
  3. Downstream Convergence: Secondary workstations pull the latest changes and align their system state to match the master list.
  ┌────────────────────────────────────────────────────────┐
  │                 Mac Studio (Master)                    │
  │   - Installs/Removes packages natively                 │
  │   - Auto-dumps configuration to ~/Scripts/MacOS/Brew   │
  └──────────────────────────┬─────────────────────────────┘
                             │
                             ▼ (git push)
  ┌────────────────────────────────────────────────────────┐
  │                 GitHub (Scripts Repo)                  │
  │   - Houses versioned Brewfile (Source of Truth)        │
  └──────────────────────────┬─────────────────────────────┘
                             │
                             ▼ (git pull & brew bundle)
  ┌────────────────────────────────────────────────────────┐
  │              Secondary Mac (iMac, Laptop)              │
  │   - Downloads missing tools                            │
  │   - Cleans up deprecated packages                      │
  └────────────────────────────────────────────────────────┘

2. Workstation Sync Strategy (On-Demand)#

Package versioning is synchronized on-demand using two custom aliases.

2.1 The Sync Workflow#

Whenever you install new software on one machine and want to mirror it to your other workstations, follow this flow:

  1. Step 1: Dump & Push (pushbrew) (Run on the machine where you added the software)

    • Action: Run pushbrew in your terminal.
    • How it works:
      1. It executes brew bundle dump --force which scans your local system for all installed command-line packages, GUI applications (casks), and VS Code extensions.
      2. It overwrites your local ~/Scripts/MacOS/Brew/Brewfile with this updated list (adding your new formula to the file).
      3. It automatically stages, commits, and pushes only this updated Brewfile to your ~/Scripts GitHub repository.

  2. Step 2: Pull & Install (pullbrew) (Run on the machine you want to update/mirror)

    • Action: Run pullbrew in your terminal.
    • How it works:
      1. It pulls the latest changes from the ~/Scripts repository (git pull origin main).
      2. It executes brew bundle to install any missing software listed in the updated Brewfile.
      3. It runs a dry-run check (brew bundle cleanup) to show unlisted installed packages and asks for confirmation: Proceed with uninstalling unlisted packages? [y/N]. If confirmed (y), it uninstalls unlisted packages.

3. Downstream Synchronization Protocol (Secondary Mac)#

To pull configuration changes down and align another machine to the master package list, use the synchronization protocol.

3.1 Initial Setup (Clone & Install)#

On a new or unconfigured Mac:

  1. Install Homebrew first: 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. Clone the repository and run the installer: 
    git clone git@github.com:marcoue/Scripts.git ~/Scripts
brew bundle --file=~/Scripts/MacOS/Brew/Brewfile

3.2 Regular Synchronization#

To synchronize package updates on an ongoing basis:

# Pull changes and align state using interactive alias
pullbrew

3.3 The --cleanup Mechanism & Interactive Safeguard#

  • Addition: Any software listed in the Brewfile that is missing from the local computer will be downloaded and installed.
  • Removal: Any software currently installed on the local computer that is not declared in the Brewfile will be proposed for uninstallation.
  • Interactive Safety: pullbrew prints the list of unlisted packages first and prompts Proceed with uninstalling unlisted packages? [y/N] so packages are never deleted without explicit approval.

3.4 Custom Command Aliases#

You can define command shortcuts in your ~/.zshrc to manually force a push or pull of your environment configuration.

Add these entries to your shell profile:

# Dump Brewfile and push ONLY Brewfile changes to GitHub
alias pushbrew='brew bundle dump --file=~/Scripts/MacOS/Brew/Brewfile --force && (cd ~/Scripts && git add MacOS/Brew/Brewfile && git commit -m "Auto-update Brewfile" && git push origin main)'

# Pull latest software config, apply missing packages, and interactively prompt before cleanup
alias pullbrew='(cd ~/Scripts && git pull origin main) && brew bundle --file=~/Scripts/MacOS/Brew/Brewfile && (echo "\n--- Checking for unlisted packages ---" && brew bundle cleanup --file=~/Scripts/MacOS/Brew/Brewfile; echo -n "\nProceed with uninstalling unlisted packages? [y/N] " && read -r response && [[ "$response" =~ ^[Yy]$ ]] && brew bundle --file=~/Scripts/MacOS/Brew/Brewfile --cleanup || echo "Skipped package cleanup.")'

Behavior when no Homebrew changes exist (pushbrew): If no packages were installed or removed since the last dump, Brewfile is unchanged. Git will exit with nothing to commit, working tree clean (or list unstaged repository files like modified scripts), which is normal. To commit general script changes across ~/Scripts/, use pushscripts.

4. Implementation & Verification#

This setup has been fully implemented on your workstation:

  • Brew Directory Created: Local configuration stored at ~/Scripts/MacOS/Brew/.
  • Initial Brewfile Generated: Initial workstation backup created and tracked.
  • Git Repository Synced: Pushed to git@github.com:marcoue/Scripts.git and auto-mirrored to UNAS-Pro NAS.
  • Shell Profiles Updated: pushbrew/pullbrew and pushscripts/pullscripts aliases added via MacOS-Aliases.zsh.

4.5 Workstation Software Inventory#

Below is the current index of software packages managed by the master Brewfile (~/Scripts/MacOS/Brew/Brewfile):

🛠️ Command-Line Formulae#

  • dcraw: Digital camera RAW photo decoding.
  • docker-compose: Multi-container Docker orchestration tool.
  • fio: Flexible I/O tester and benchmark tool.
  • gemini-cli: Google Gemini AI model command-line agent interface.
  • hugo: Fast open-source static site generator.
  • imagemagick: Digital image editing and manipulation suite.
  • iperf3: Network bandwidth testing and measurements.
  • mole: System diagnostics and cleaner tool.
  • node: Node.js Javascript runtime platform.
  • pssh: Parallel OpenSSH automation tools.
  • tmux: Terminal session multiplexer.
  • uv: Fast Python package management and installer tool.
  • wakeonlan: Broadcast packet utility to wake devices.
  • wget: File retriever tool.

🖥️ Desktop Applications (Casks)#

  • 1password-cli: 1Password developer command-line tool.
  • codex: OpenAI Codex interactive coding agent terminal interface (Homebrew Cask).
  • darktable: RAW photography workflow developer application.
  • fuse-t: Kext-less user-space filesystem driver.
  • fuse-t-sshfs: Secure shell filesystem mounting tool using FUSE-T.
  • vscodium: VS Code text editor without Microsoft telemetry tracking.

🔌 VS Code / VSCodium Extensions#

  • donjayamanne.githistory: Git history viewer.
  • github.vscode-pull-request-github: GitHub pull requests and code review helper.
  • google.gemini-cli-vscode-ide-companion: Google Gemini AI coding assistant interface.
  • jeanp413.open-remote-ssh: SSH remote project connections.
  • ms-azuretools.vscode-containers: Local container attachment tool.
  • ms-azuretools.vscode-docker: Manage Docker environments inside VS Code.
  • redhat.vscode-xml: XML file linting and formatting support.
  • redhat.vscode-yaml: YAML file structure validation.
  • rooveterinaryinc.roo-cline: AI coding assistant.
  • vscode-icons-team.vscode-icons: File tree icon pack layouts.
  • yzhang.markdown-all-in-one: Markdown creation shortcuts and formatting helper.
  • zoocodeorganization.zoo-code: AI coding assistant.

🌐 Model Context Protocol (MCP) Servers & Packages#

  • @cloudflare/mcp-server-cloudflare: Cloudflare services API tool.
  • @cyanheads/git-mcp-server: Git version control interface.
  • @earendil-works/pi-coding-agent: Remote Raspberry Pi execution controller.
  • @modelcontextprotocol/server-github: GitHub repositories connector.
  • @modelcontextprotocol/server-postgres: Postgres SQL query executor.
  • @thelord/unifi-mcp-server: Unifi gateway device manager.
  • mcp-pihole-server: Pi-hole local DNS controller.
  • mcp-server-docker: Local Docker execution manager.
  • n8n-mcp: n8n workflow executor tool.
  • shell-exec-mcp: Remote command execution controller.
  • xcodebuildmcp: Xcode compile controller.

5. Related Notes#

Backward Mac OS - Aliases Management Mac OS - Recovery Forward