devAlice
← Mac

Gestión de Brewfile: reproduce un entorno de desarrollo Mac como código con `brew bundle`

Un patrón con Brewfile que fija tu configuración Mac en un solo archivo. dump → cleanup → install en otra máquina: un ciclo completo.

Escribir brew install línea por línea cada vez que configuras un Mac nuevo es ineficiente. brew bundle permite que un único Brewfile agrupe fórmulas de brew, casks, extensiones de VS Code e incluso apps de la App Store en algo reproducible. Una vez que internalizas el patrón, los cambios de máquina y la incorporación de compañeros de equipo se reducen en incrementos de 30 minutos.

Esta guía está dirigida a macOS 14+ / Homebrew 4.x. Es el paso de congelar tu entorno como código después de la configuración inicial de Mac.

TL;DR

  1. Usa brew bundle dump --describe para capturar el estado actual en un Brewfile
  2. Edita manualmente (elimina paquetes duplicados y de prueba) → haz commit a Git
  3. En un Mac nuevo: brew bundle install --file=./Brewfile → listo
  4. Periódicamente brew bundle cleanup para eliminar lo que no está en el Brewfile

Requisitos previos

  • Homebrew 4.x instalado — ver configuración inicial de Mac
  • (Opcional) Un repo o Gist en GitHub (para almacenar el Brewfile)
  • (Opcional) mas-cli — brew install mas si quieres incluir apps de la Mac App Store también

Descargar un Brewfile de ejemplo

La línea base recomendada de devAlice — descárgala y edítala según tu entorno.

Brewfile 
# 1. Descargar
curl -fsSL https://devalice.jaceclub.com/assets/mac/brewfile-management/Brewfile.example -o Brewfile
 
# 2. Verificar SHA-256
shasum -a 256 Brewfile
# Esperado: 2b54214d29391d15666fe5e15768aa2e6e6eabea8b3c772989d6e1216a816c5f
 
# 3. Inspeccionar (revisa qué paquetes tiene; edita para adaptarlo a tu entorno)
less Brewfile
 
# 4. Aplicar
brew bundle install --file=./Brewfile

1. Sintaxis básica de Brewfile — 5 min

Es un DSL de Ruby internamente, pero en realidad solo necesitas cinco palabras clave.

# Brewfile
 
# tap — repositorio adicional
tap "homebrew/bundle"
tap "homebrew/services"
 
# brew — fórmulas (herramientas CLI)
brew "git"
brew "gh"
brew "mise"
 
# Se permiten argumentos opcionales
brew "postgresql@16", restart_service: :changed
brew "redis",         start_service: true
 
# cask — apps con interfaz gráfica
cask "visual-studio-code"
cask "rectangle"
 
# Mac App Store (requiere mas-cli)
mas "Xcode", id: 497799835
 
# Extensiones de VS Code (sintaxis similar a mas)
vscode "dbaeumer.vscode-eslint"
vscode "esbenp.prettier-vscode"

Comentarios + secciones

# ─── CLI ──────────────────────────────────────
brew "git"
brew "gh"
 
# ─── GUI ──────────────────────────────────────
cask "visual-studio-code"

Los separadores de sección mejoran mucho el mantenimiento: los diffs se vuelven más legibles después de cada commit.

2. Generar un Brewfile desde el estado actual (dump) — 3 min

Si ya tienes una máquina bien configurada, captúrala de una sola vez.

# Crear un Brewfile en el directorio actual (--force sobreescribe)
brew bundle dump --force --describe
 
# --describe añade un comentario # a cada línea — legibilidad ↑

Salida de ejemplo:

# ./Brewfile (generado automáticamente)
tap "homebrew/services"
brew "git"
# Distributed revision control system
brew "gh"
# GitHub command-line tool
brew "jq"
# Lightweight and flexible command-line JSON processor
brew "mise"
# Polyglot runtime manager (asdf rust clone)
cask "visual-studio-code"
# Open-source code editor

Limpia el dump manualmente

Un dump reciente captura todo lo instalado actualmente, que normalmente tiene ruido. Lista de limpieza:

  1. Paquetes solo de prueba que ya no usas → elimínalos
  2. Runtimes de lenguajes → elimínalos si los gestionarás con mise (p.ej., node, python@3.x)
  3. Trabajo vs personal → divide en Brewfile.work / Brewfile.personal
  4. Añade comentarios de sección

Dedicar 10 minutos ahora ahorra una hora de configuración en el futuro.

3. Aplicar en otra máquina (install) — 10–30 min

En el directorio que contiene tu Brewfile, en la máquina nueva (o después de la limpieza):

brew bundle install --file=./Brewfile
 
# O usa una ruta absoluta
brew bundle install --file=$HOME/dotfiles/Brewfile
 
# Los elementos ya instalados se omiten (idempotente)

La primera ejecución está dominada por las descargas de casks (~50–200MB cada una). Planifica 10–30 minutos.

Vista paso a paso — --verbose

brew bundle install --file=./Brewfile --verbose

Solo fallos — --quiet

brew bundle install --file=./Brewfile --quiet

4. Eliminar paquetes que no están en el Brewfile (cleanup) — 5 min

Para que tu Brewfile sea la única fuente de verdad, elimina todo lo que no esté listado.

# Simulacro — ver qué se eliminaría
brew bundle cleanup --file=./Brewfile
 
# Eliminar realmente — sé deliberado
brew bundle cleanup --file=./Brewfile --force

⚠️ --force desinstala inmediatamente. Ejecútalo después de que tu Brewfile esté completamente limpio; de lo contrario puede que necesites reinstalar.

5. Estrategia de división — work / personal / experiment

Un único Brewfile monolítico eventualmente se infla. Divide por contexto.

~/dotfiles/
├── Brewfile           # Común a todos (esenciales CLI)
├── Brewfile.work      # Solo trabajo (Slack, Zoom, ...)
├── Brewfile.personal  # Personal (lanzadores de juegos, ...)
└── Brewfile.optional  # Uso ocasional

Aplícalos juntos

cd ~/dotfiles
brew bundle install --file=./Brewfile
brew bundle install --file=./Brewfile.work
brew bundle install --file=./Brewfile.personal

O vía Makefile/script de shell

# ~/dotfiles/bundle.sh
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")"
for f in Brewfile Brewfile.work Brewfile.personal; do
  [ -f "$f" ] && brew bundle install --file="./$f"
done
echo "✓ Todos los Brewfiles aplicados"

6. Control de versiones con Git — 3 min

Un Brewfile es un archivo central en cualquier repo de dotfiles.

cd ~/dotfiles
git init
git add Brewfile Brewfile.*
git commit -m "feat: initial Brewfile baseline"
git remote add origin git@github.com:<user>/dotfiles.git
git push -u origin main

Cuando añadas/elimines paquetes más adelante:

brew bundle dump --force --describe   # actualizar
git diff Brewfile                     # revisar cambios
git commit -am "feat: add postgresql + redis"
git push

En una máquina nueva:

git clone git@github.com:<user>/dotfiles.git ~/dotfiles
cd ~/dotfiles
brew bundle install --file=./Brewfile

7. Automatización: brew services + macOS LaunchAgent

Programa un volcado automático diario para que tu estado de brew no se desfase.

~/Library/LaunchAgents/dev.local.brewdump.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>dev.local.brewdump</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>-lc</string>
    <string>cd $HOME/dotfiles && /opt/homebrew/bin/brew bundle dump --force --describe</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict><key>Hour</key><integer>22</integer><key>Minute</key><integer>0</integer></dict>
</dict>
</plist>
launchctl load ~/Library/LaunchAgents/dev.local.brewdump.plist

Volcado automático a las 22:00 cada día. Cada mañana, git diff muestra qué cambió durante la noche.

8. Solución de problemas

«Error: Cask 'X' is not installed» (durante cleanup)

El cask ya se eliminó en otro lugar. Vuelve a ejecutar brew bundle cleanup --force para reconciliar.

El dump captura demasiados paquetes no deseados

Son dependencias transitivas antiguas que aparecen como paquetes de nivel superior. Ordénalas:

brew autoremove   # elimina paquetes hoja usados solo como deps
brew bundle dump --force --describe  # vuelve a hacer dump

Las apps de la App Store no aparecen en el dump

Falta mas-cli. brew install mas y vuelve a hacer dump.

Algunos casks fallan en SHA-256 durante la instalación

Ocurre justo después de que Homebrew actualiza las definiciones de cask. brew update y reintenta.

Próximos pasos

Referencias

Historial de cambios

  • 2026-05-12 — Primera versión (expansión semilla devAlice M2)