Gestión de dotfiles: chezmoi vs yadm vs symlinks manuales, edición Mac

Si todavía copias y pegas .zshrc, .gitconfig y archivos ~/.config/... cada vez que obtienes un Mac nuevo, necesitas una herramienta de gestión de dotfiles. Configúrala una vez, y una máquina nueva restaura su configuración completa con un único comando.

Esta guía compara tres enfoques (chezmoi · yadm · symlink manual + Git) y recorre en detalle la configuración recomendada de chezmoi.

TL;DR

1. Por qué una herramienta de dotfiles

Poner .zshrc directamente en un repo Git y vincularlo con symlink funciona. Pero estos problemas se acumulan:

• Diferencias por máquina: git user.email del Mac de trabajo vs el personal; la ramificación acaba codificada a mano.
• Secretos: mezclar claves API o configuración SSH es peligroso, y es fácil olvidarse del .gitignore.
• Bidireccionalidad: si editas ~/.zshrc directamente, el repositorio se desfasa y pierdes el rastro de cuál es la fuente de verdad.
• Máquina nueva: clonar, instalar dependencias, crear symlinks, ajustar permisos… cada vez.

Una herramienta de dotfiles envuelve esto en un flujo de trabajo consistente.

2. Opciones comparadas

chezmoi

CLI basado en Go. Motor de templates (ramificación por máquina), secretos (integración con 1Password / Bitwarden), bidireccional (chezmoi diff / chezmoi apply).

yadm

Un wrapper de Git que trata los dotfiles en ~ como un repositorio Git directo. Cero costo de aprendizaje. La ramificación por máquina está soportada pero es limitada (archivos alt como .zshrc##os.Darwin).

Symlink manual + Git

Pon los archivos en ~/dotfiles/ y crea symlinks con un script de instalación. El más transparente, pero tú construyes cada característica.

Recomendación: chezmoi

Para un único usuario con 1–3 máquinas, chezmoi gana de forma clara. Una hora de aprendizaje se rentabiliza de por vida.

3. Configuración de chezmoi

3.1 Instalar

brew install chezmoi

3.2 Preparar un repo en GitHub

Crea un repo dotfiles privado en GitHub (el nombre es tu elección). Vacío está bien.

3.3 Inicializar chezmoi

chezmoi init github.com/yourname/dotfiles
# O, si SSH está disponible:
chezmoi init git@github.com:yourname/dotfiles.git

~/.local/share/chezmoi/ se convierte en el árbol de trabajo (el repo Git real).

3.4 Añadir archivos

# Poner .zshrc bajo gestión de chezmoi
chezmoi add ~/.zshrc
 
# O varios a la vez
chezmoi add ~/.gitconfig ~/.tmux.conf ~/.config/starship.toml

Los archivos se copian como ~/.local/share/chezmoi/dot_zshrc (punto inicial → prefijo dot_).

3.5 Commit + Push

chezmoi cd          # ir al árbol de trabajo
git add .
git commit -m "init dotfiles"
git push -u origin main
exit                # volver a donde estabas

3.6 Restaurar en una máquina nueva

# En el Mac nuevo
brew install chezmoi
chezmoi init --apply github.com/yourname/dotfiles

Listo. Todos los dotfiles se materializan en ~ y se aplican inmediatamente.

4. Ramificación por máquina (templates)

La característica más potente de chezmoi. El mismo .gitconfig se adapta a trabajo vs personal:

~/.local/share/chezmoi/dot_gitconfig.tmpl

Contenido:

[user]
    name = Your Name
{{- if eq .chezmoi.hostname "Work-MacBook" }}
    email = me@company.com
    signingkey = AAAA....
{{- else }}
    email = personal@example.com
{{- end }}
 
[core]
    editor = nvim
    autocrlf = input

La extensión .tmpl marca un template. chezmoi ramifica según el hostname al aplicar.

4.1 Variables disponibles

chezmoi data       # imprimir todas las variables de contexto

Usadas comúnmente:

• .chezmoi.os — darwin / linux / windows
• .chezmoi.hostname — nombre de la máquina
• .chezmoi.arch — arm64 / amd64
• Personalizadas — añadir con chezmoi edit-config

4.2 Archivos específicos por SO

Renombra dot_zshrc a dot_zshrc.tmpl y ramifica por SO:

{{ if eq .chezmoi.os "darwin" -}}
# Solo macOS
export HOMEBREW_PREFIX="/opt/homebrew"
eval "$($HOMEBREW_PREFIX/bin/brew shellenv)"
{{ else if eq .chezmoi.os "linux" -}}
# Solo Linux
export PATH="$HOME/.linuxbrew/bin:$PATH"
{{ end -}}
 
# Compartido
alias ll='ls -lah'

5. Integración de secretos

Nunca escribas claves API o tokens directamente en los dotfiles. Usa la integración de herramientas de secretos de chezmoi:

CLI de 1Password

brew install --cask 1password 1password-cli
op signin

dot_ssh/config.tmpl:

Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal
  PreferredAuthentications publickey

dot_env.tmpl referenciando secretos:

export ANTHROPIC_API_KEY={{ onepasswordRead "op://Private/Anthropic/api_key" }}
export GITHUB_TOKEN={{ onepasswordRead "op://Private/GitHub/token" }}

Al ejecutar chezmoi apply, recupera los valores de 1Password y escribe un .env en texto plano. Ese archivo está en .gitignore, por lo que nunca entra al repositorio.

Bitwarden / pass / age

Cada uno tiene integración oficial con chezmoi — ver docs.chezmoi.io.

6. Flujo de trabajo

Diario

# Después de editar ~/.zshrc directamente
chezmoi diff       # ver qué cambió
chezmoi add ~/.zshrc   # propagar de vuelta al repo
chezmoi cd && git commit -am "tweak zshrc" && git push

Sincronizar otra máquina

chezmoi update     # git pull + apply

Previsualizar cambios

chezmoi diff       # cambios antes de aplicar
chezmoi apply -v   # aplicación verbose

Editar fuente

chezmoi edit ~/.zshrc   # edita la fuente (= repo) y aplica automáticamente

7. yadm — la alternativa más ligera

Si el cero costo de aprendizaje es tu prioridad, yadm:

brew install yadm
yadm init
yadm add ~/.zshrc
yadm commit -m "init"
yadm remote add origin git@github.com:yourname/dotfiles.git
yadm push -u origin main
 
# Otra máquina
yadm clone git@github.com:yourname/dotfiles.git

Los comandos son idénticos a git (solo difiere el binario). Desventaja: la ramificación por máquina se limita a archivos alt como .zshrc##os.Darwin.

8. Symlink manual + Git

Mínimas dependencias:

mkdir ~/dotfiles && cd ~/dotfiles
git init
mv ~/.zshrc ~/dotfiles/zshrc
ln -s ~/dotfiles/zshrc ~/.zshrc
 
# install.sh
#!/usr/bin/env bash
for f in zshrc gitconfig tmux.conf; do
  ln -sf "$HOME/dotfiles/$f" "$HOME/.$f"
done

Limpio, pero implementas los secretos, la ramificación y el bootstrap tú mismo. La mayoría migra a chezmoi en un año.

Verificación

1. chezmoi diff → sin cambios (todo aplicado correctamente).
2. Edita ~/.zshrc directamente → chezmoi diff muestra la diferencia.
3. En una máquina nueva (o VM limpia): chezmoi init --apply github.com/you/dotfiles → todos los dotfiles restaurados.
4. Tras modificar un template, chezmoi apply -v → salida diferente según el hostname.
5. Con la integración de 1Password, chezmoi apply escribe ~/.env en texto plano, pero el repositorio no lo contiene.

Solución de problemas

chezmoi apply no cambia nada

• Revisa chezmoi diff. Si está vacío, es el comportamiento esperado.
• Las diferencias de permisos de archivo pueden ocultar cambios: prueba chezmoi apply --force.

Errores de sintaxis en templates

{{ ... }} son templates de Go. Un cierre -}} faltante o un error tipográfico en un nombre de variable son errores habituales. Haz una prueba en seco con chezmoi execute-template < dot_gitconfig.tmpl.

La integración de 1Password falla

• Tras op signin, la sesión es válida ~30 minutos por defecto. Vuelve a ejecutar eval $(op signin).
• Activa 1Password explícitamente en chezmoi.toml (chezmoi edit-config).

Faltan claves SSH en una máquina nueva

Nunca almacenes claves SSH en los dotfiles (riesgo de seguridad). Genera claves nuevas en la máquina nueva y regístralas en GitHub. chezmoi solo debe gestionar archivos de configuración como ~/.ssh/config.

~/.zshrc no se actualiza al editarlo directamente

Usa chezmoi edit ~/.zshrc para editar la fuente y que se aplique automáticamente. O edita la fuente directamente y ejecuta chezmoi apply.

Referencias

• Configuración inicial de Mac — Homebrew etc. antes de los dotfiles
• Sincronización de archivos Mac↔Win — Syncthing para notas/proyectos, separado de los dotfiles
• chezmoi (oficial)
• yadm

Historial de cambios

• 2026-05-12: Primera versión. Tres enfoques comparados + configuración práctica de chezmoi (templates / secretos / flujo de trabajo) + cinco casos de solución de problemas.