Chezmoi: sincroniza tus dotfiles entre máquinas sin perder la cabeza

JaimeAlberto
Sysadmin, Herramientas
Chezmoi: sincroniza tus dotfiles entre máquinas sin perder la cabeza

Tengo dos máquinas. Mi workstation el .zshrc lleva semanas con funciones que en mi portatil no conoce. En el portatil hay aliases que en el workstation no existen. Y cada vez que abro una terminal en el portátil me acuerdo de que tendría que sincronizar algo.

La solución obvia es git. El problema es montarlo bien: symlinks que se rompen, scripts de bootstrap que fallan en la segunda máquina, bare repos que nadie entiende a la semana de crearlos.

chezmoi resuelve eso. Sin symlinks, sin magia negra. Un comando y los dotfiles están donde tienen que estar.

Chezmoi: sincroniza tus dotfiles entre máquinas sin perder la cabeza

Índice

El problema de los dotfiles

El .zshrc está en el portátil del trabajo. Lo modificas, añades una función nueva, mejoras los aliases. Pasan dos semanas. Abres el de casa y la función no está. Abres el equipo de viaje: versión de hace cuatro meses.

Me ha pasado más veces de las que debería admitir.

Los dotfiles viajan por correo, por pendrive, por scp a mano, o directamente no viajan. Cada máquina acaba con su versión, llevas meses sin saber cuál es la canónica, y llegado un punto ya te da igual porque tampoco vas a reconciliar nada a mano.

La solución obvia es git. El problema es que gestionar dotfiles con git directamente —symlinks, bare repos, scripts de bootstrap— lleva más tiempo montarlo que lo que tarda en romperse. chezmoi resuelve exactamente eso.

Qué es chezmoi y qué no es

chezmoi mete tus dotfiles en un repo git pero añade una capa encima que hace el trabajo sucio: renombra los ficheros para preservar los puntos (dot_zshrc → ~/.zshrc, private_dot_config/ → ~/.config/), los gestiona en ~/.local/share/chezmoi/ y los sincroniza con un repo git normal. Sin magia. Sin symlinks.

Lo que hace bien:

  • Aplica dotfiles en máquinas nuevas con un solo comando
  • Gestiona ficheros con distintas variantes por máquina (templates)
  • Soporta ficheros cifrados para secretos que sí necesitas versionar
  • No depende de symlinks — copia los ficheros donde corresponde

Lo que no hace, y esto conviene saberlo desde el principio: no detecta cambios automáticamente. Si editas ~/.zshrc directamente, chezmoi no se entera hasta que ejecutas re-add. Yo tardé en darme cuenta. La sección de sync explica cómo automatizarlo.

Instalación

sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin

Esto instala el binario en ~/.local/bin/chezmoi. Verifica que ~/.local/bin está en tu $PATH.

chezmoi --version
# chezmoi version v2.70.4

Inicializa el repo:

chezmoi init

Esto crea ~/.local/share/chezmoi/ como repo git vacío. Si ya tienes un repo existente en GitHub:

chezmoi init --apply [email protected]:tuusuario/dotfiles.git

Añadir ficheros al repo

# Añadir un fichero
chezmoi add ~/.zshrc
chezmoi add ~/.p10k.zsh
chezmoi add ~/.gitconfig

# Añadir ficheros de configuración (se guardan como private_dot_config/)
chezmoi add ~/.config/Code/User/settings.json

Los ficheros que empiezan por punto se guardan con prefijo dot_. Los que están en ~/.config/ se guardan como private_dot_config/ (marcados como privados, chmod 600 al aplicar).

Para ver qué gestiona chezmoi:

chezmoi managed

Para hacer commit y push al repo:

cd ~/.local/share/chezmoi
git add -A && git commit -m "add: zshrc, p10k, gitconfig"
git push

Aplicar en una segunda máquina

En cualquier máquina nueva:

# Instalar chezmoi
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin

# Inicializar desde el repo y aplicar en un solo paso
chezmoi init --apply [email protected]:tuusuario/dotfiles.git

chezmoi descarga el repo y aplica cada fichero en su ruta original. Sin scripts de bootstrap, sin symlinks que mantener.

⚠️ Si tienes ficheros KDE capturados en Plasma 5 + X11, revisar compatibilidad antes de aplicar en Plasma 6 + Wayland. Algunos atajos de kglobalshortcutsrc pueden quedar obsoletos.

El problema del sync automático y la solución

chezmoi no detecta cambios en los ficheros originales. Si editas ~/.zshrc directamente, la copia en ~/.local/share/chezmoi/ no se actualiza sola. Tienes que ejecutar re-add manualmente:

# Actualizar un fichero ya gestionado tras modificarlo
chezmoi re-add ~/.zshrc

# Ver qué ha cambiado respecto al repo
chezmoi diff

En la práctica esto significa que es fácil olvidarse de hacer el re-add y acabar con el repo desactualizado.

La solución que uso: una función en ~/.zshrc que sincroniza al ejecutarla, más un hook de apagado de KDE que la ejecuta automáticamente al cerrar sesión.

Función en .zshrc:

dotfiles-sync() {
  echo "Sincronizando dotfiles con chezmoi..."
  chezmoi re-add ~/.zshrc ~/.p10k.zsh ~/.gitconfig \
    ~/.config/Code/User/settings.json \
    ~/.config/kglobalshortcutsrc
  cd ~/.local/share/chezmoi
  if [[ -n $(git status --porcelain) ]]; then
    git add -A && git commit -m "auto: sync $(date +%Y-%m-%d)"
    git push && echo "✓ dotfiles sincronizados y pusheados"
  else
    echo "✓ Sin cambios"
  fi
  cd -
}

Hook de apagado KDE (~/.config/plasma-workspace/shutdown/sync-dotfiles.sh):

#!/bin/bash
~/.local/bin/chezmoi re-add ~/.zshrc ~/.p10k.zsh ~/.gitconfig \
  ~/.config/Code/User/settings.json
cd ~/.local/share/chezmoi
git add -A && git commit -m "auto: shutdown sync $(date +%Y-%m-%d)" --allow-empty
git push

chmod +x ~/.config/plasma-workspace/shutdown/sync-dotfiles.sh

Con esto, los dotfiles se sincronizan solos al cerrar sesión en KDE. Sin acordarse de nada.

Lo que no entra en el repo nunca

No todo debe estar en el repo de dotfiles, aunque sea privado:

FicheroPor qué no
~/.ssh/Claves privadas — backup manual en disco externo cifrado
~/.gnupg/Claves GPG — backup manual en disco externo cifrado
~/.config/app/tokensTokens OAuth de aplicaciones — backup manual cifrado
~/.app.jsonConfiguraciones con rutas locales — distintas por máquina

Mi regla: si un fichero contiene secretos o tiene rutas que cambian por máquina, no entra en el repo. Punto. Para secretos que sí necesitas versionar —API keys, tokens de servicios— chezmoi tiene cifrado nativo con age o GPG. Pero eso da para otro artículo.

Las configuraciones y pasos descritos se han probado en infraestructura propia con Debian 12 y chezmoi v2.70.4. Adáptalos siempre a tu entorno antes de aplicarlos. La función dotfiles-sync y el hook de apagado asumen KDE Plasma — en otros entornos de escritorio el mecanismo de shutdown hooks es distinto. El autor no se hace responsable de pérdidas de datos o configuraciones sobreescritas derivadas de su aplicación sin las adaptaciones necesarias.

Llevo usando este flujo en mi workstation y el portátil desde que monté la infra. El hook de apagado de KDE es lo que más agradezco: no hay que acordarse de nada. Cierras sesión y los dotfiles viajan solos.

Si gestionas más de una máquina Linux, el tiempo que tardas en instalar chezmoi lo recuperas en la primera vez que arrancas el portátil y todo está exactamente donde lo dejaste.

El siguiente paso natural es versionar también los secretos con cifrado nativo de chezmoi. Eso es otro artículo.

Proyecto: chezmoi.io · GitHub