Cómo gestionar tus .dotfiles con GNU Stow paso a paso

Si usas Linux, macOS o Termux en Android a diario, tarde o temprano acabas acumulando un montón de archivos de configuración repartidos por todo tu directorio personal: .zshrc, .bashrc, .config, nvim, Hyprland, etc. Cuando solo tienes un equipo se sobrevive, pero en cuanto trabajas con varios ordenadores o servidores mantener todo esto a mano ya es otra historia.

En este contexto entra en juego GNU Stow, un gestor de enlaces simbólicos que se ha convertido en una de las formas más limpias, sencillas y reversibles de gestionar dotfiles. No es el único enfoque posible (existen alternativas como repositorios bare de Git, yadm, Chezmoi, Dotbot…), pero su filosofía minimalista encaja de lujo si quieres algo potente sin demasiada magia por detrás.

Qué es exactamente GNU Stow y por qué sirve para gestionar .dotfiles

GNU Stow es, en origen, un “symlink farm manager”: una herramienta pensada para organizar varios “paquetes” de ficheros en un solo lugar y exponerlos en otro directorio mediante enlaces simbólicos. Aunque se ideó para gestionar instalaciones locales de software, la comunidad lo adoptó rápidamente para manejar dotfiles porque encaja como un guante.

La idea base es muy simple: guardas todas tus configuraciones en un único repositorio central (por ejemplo ~/dotfiles), estructuradas como si fueran a vivir en tu $HOME, y Stow se encarga de crear symlinks desde tu carpeta personal hacia esos archivos. Así puedes versionarlos con Git, clonarlos en más máquinas y reproducir tu entorno con uno o pocos comandos.

Algo importante: Stow no es “una herramienta de dotfiles” en el sentido estricto; no almacena estado propio, no lleva base de datos, ni plantillas, ni cifrado. Se limita a crear y eliminar enlaces simbólicos siguiendo una estructura de directorios. Precisamente por eso es tan fácil de entender y revertir.

Esta filosofía minimalista contrasta con soluciones más complejas tipo Chezmoi, que añaden plantillas, gestión de secretos, integración con gestores de contraseñas y un flujo de trabajo más automatizado. Con Stow tú mandas: todo está en el sistema de ficheros y en tu repo Git, sin capas intermedias.

Ventajas de usar Stow frente a otras formas de gestionar dotfiles

Antes de que Stow se pusiera de moda, mucha gente gestionaba sus dotfiles a base de “cp” y “mv”: se copiaban configuraciones a mano entre equipos o mantenían un repo donde había que acordarse de actualizar continuamente. Era fácil acabar con varias versiones del mismo archivo y no tener claro cuál estaba realmente en uso.

Con Stow, todos los archivos “reales” viven en tu directorio de dotfiles y en tu $HOME solo tienes enlaces simbólicos. Eso significa que, cuando editas por ejemplo ~/.zshrc, en realidad estás modificando el fichero que está dentro de tu repo. No hay duplicados, no hay desincronización, no hay que recordar qué copiar a dónde.

Otra ventaja clara es la reversibilidad: si quieres deshacer lo que ha hecho Stow, basta con ejecutar “stow -D paquete” desde tu carpeta de dotfiles y elimina todos los enlaces simbólicos creados para ese paquete. No borra tus configuraciones reales (que siguen en el repo), solo limpia los symlinks del destino.

Además, Stow se lleva muy bien con Git: puedes versionar ~/dotfiles como un repositorio normal, hacer commits, ramas, usar GitHub o GitLab como copia de seguridad, etc. Stow ya ignora automáticamente la carpeta .git cuando genera enlaces, con lo que no corres el riesgo de llenar tu $HOME de archivos internos de Git.

Por último, a diferencia de otras herramientas más pesadas, Stow suele estar disponible en cualquier distro Linux e incluso en macOS mediante Homebrew, es básicamente un script en Perl con muy pocas dependencias y funciona en cualquier entorno tipo UNIX.

Alternativas habituales: Git bare, yadm, Chezmoi, Dotbot…

Cuando te planteas gestionar dotfiles de forma seria, suele aparecer siempre la misma lista de opciones: repositorio Git “bare”, yadm, Dotbot, Chezmoi, además de Stow. Cada enfoque tiene su estilo y su público, así que conviene situar a Stow dentro de ese ecosistema.

El método del repositorio Git bare consiste en inicializar un repo sin working tree asociado y usar alias de Git para que el propio $HOME actúe como directorio de trabajo. Ventajas: no hay enlaces simbólicos, Git trabaja directamente sobre tus archivos reales y el flujo de comandos es muy simple. Muchos usuarios comentan que les sorprendió lo fácil que era seguir un tutorial tipo “DT” y tenerlo funcionando sin tocar symlinks.

Por otra parte, Chezmoi se centra de lleno en la gestión avanzada de dotfiles: plantillas para manejar diferencias entre máquinas, integración con gestores de contraseñas, cifrado de archivos con gpg o age, hooks para ejecutar scripts durante la instalación, soporte multiplataforma muy cuidado, etc. Es ideal si necesitas gestionar secretos, soportar muchos sistemas distintos o automatizar instalaciones complejas.

Stow se sitúa en el extremo opuesto: no sabe nada de secretos, ni plantillas, ni scripts. Se limita a crear symlinks de forma limpia. Para muchos usuarios eso es una virtud: menos cosas que aprender, menos comportamiento “mágico” y una mayor transparencia. Si necesitas lógica condicional pesada, seguramente Chezmoi te encaje mejor; si solo quieres mantener tus configs ordenadas sin complicarte, Stow es un clásico muy fiable.

También existen herramientas como yadm o Dotbot, que automatizan montones de tareas (incluso ejecutar scripts post-instalación, clonar repos, instalar paquetes…). Aun así, un buen número de desarrolladores sigue prefiriendo Stow porque es fácil de auditar, se integra bien con los flujos de Git ya conocidos y se adapta sin problemas tanto a setups minimalistas como a escritorios más pesados.

Enfoques de organización: repo unificado vs repositorio basado en paquetes

Cuando empiezas a usar Stow, una de las primeras decisiones que tienes que tomar es cómo estructurar tu repositorio de dotfiles. A grandes rasgos, hay dos patrones populares: el enfoque unificado y el enfoque basado en paquetes.

En el modelo unificado, tu repo de dotfiles tiene prácticamente la misma forma que tu directorio $HOME: archivos como .bashrc o .zshrc en la raíz, y carpetas como .config/nvim o .config/lazygit dentro. Algo del estilo:

dotfiles-unificado/
├── .bash_aliases
├── .bash_completion/
│ └── alacritty.bash
├── .bashrc
└── .config/
├── lazygit/config.yml
└── nvim/…

Con este diseño, entras en la carpeta del repo, ejecutas stow . y, de golpe, todas tus configuraciones quedan enlazadas en tu $HOME. Es tremendamente cómodo cuando quieres clonar tu entorno completo en una nueva máquina con un solo comando y no necesitas demasiada diferenciación entre equipos.

El enfoque basado en paquetes funciona diferente: creas un subdirectorio por “módulo” o aplicación. Por ejemplo, uno para bash, otro para nvim, otro para lazygit, otro para zsh, otro para Hyprland, etc. Cada directorio contiene los archivos con la ruta completa que tendrían en tu $HOME. Algo como:

dotfiles-packages/
├── bash/
│ ├── .bash_aliases
│ ├── .bash_completion/alacritty.bash
│ └── .bashrc
├── lazygit/.config/lazygit/config.yml
└── nvim/.config/nvim/…

Con este esquema puedes decidir qué paquetes “activar” en cada máquina: en un equipo ejecutas “stow bash nvim lazygit”, en otro quizá “stow zsh nvim”. Es muy útil cuando trabajas con varias distribuciones (por ejemplo Arch en un PC y Fedora en otro) o con shells distintas (fish en un equipo, bash en otro) y quieres mantener todo en un solo repo, pero elegir qué aplicar en cada entorno.

¿La pega? Es algo más complejo: ya no vale con stow . y listo, tienes que recordar qué paquetes necesitas, o bien crear un pequeño script por máquina que llame a Stow con la combinación adecuada. Aun así, muchos usuarios prefieren este control fino, sobre todo si tienen software muy específico por equipo.

Cómo funciona Stow por dentro: el concepto de “mirroring” de directorios

El truco fundamental para entender Stow es su sistema de reflejar estructuras de directorios (directory mirroring). Stow no adivina rutas; simplemente mira cómo están organizados los archivos dentro del “paquete” y coloca los symlinks correspondientes en el directorio destino.

Por ejemplo, si una aplicación espera su configuración en:

~/.config/ghostty/

tu módulo dentro de ~/dotfiles debería tener exactamente esa ruta relativa:

~/dotfiles/ghostty/.config/ghostty/

Todo lo que coloques dentro (por ejemplo un archivo llamado config) será enlazado por Stow en el lugar correcto. De este modo, Ghostty seguirá leyendo su configuración desde ~/.config/ghostty/config, pero en realidad ese fichero apunta al que está guardado en tu repo.

Este patrón se repite para cualquier herramienta: Waybar tendría algo como ~/dotfiles/waybar/.config/waybar/, Neovim ~/dotfiles/nvim/.config/nvim/, y así sucesivamente. El proceso es extremadamente uniforme, lo que hace que escalar a más programas sea casi mecánico.

Para dotfiles que viven directamente en el $HOME (como ~/.gitconfig o ~/.zshrc) la lógica es idéntica: dentro del paquete git tendrás un archivo .gitconfig en la raíz, y Stow se encargará de crear el enlace en tu directorio personal al lanzar “stow git”.

Paso a paso: montar un repositorio de dotfiles con Stow

El flujo de trabajo típico con Stow es sencillo y se puede resumir en unos cuantos pasos bien definidos, tanto en Linux como en macOS. Lo importante es acostumbrarse a que los archivos “de verdad” están siempre dentro del repo y no dispersos por tu $HOME.

Para empezar, crea el directorio donde vivirán tus dotfiles. Mucha gente usa ~/.dotfiles o ~/dotfiles, el nombre es lo de menos:

mkdir -p ~/.dotfiles
cd ~/.dotfiles

A continuación, mueve tus archivos de configuración actuales al repositorio. Por ejemplo, si tienes un .bashrc en tu home y quieres gestionarlo con Stow, podrías hacer:

mv ~/.bashrc ~/.dotfiles/.bashrc

Si prefieres el enfoque por paquetes, en lugar de dejar el archivo en la raíz del repo, lo meterías en una carpeta “bash” manteniendo la ruta completa:

mkdir -p ~/.dotfiles/bash
mv ~/.bashrc ~/.dotfiles/bash/.bashrc

El procedimiento con configuraciones que están dentro de .config es análogo: replicas la estructura de directorios dentro del repo. Por ejemplo, para Neovim podrías tener:

mkdir -p ~/.dotfiles/nvim/.config/nvim
mv ~/.config/nvim/* ~/.dotfiles/nvim/.config/nvim/

Una vez que los archivos vivan en tu repo, conviene borrar o renombrar los originales en $HOME para evitar conflictos. Más tarde, Stow se encargará de recrear los enlaces simbólicos en las rutas donde las aplicaciones esperan encontrar sus configs.

Instalar GNU Stow en distintas plataformas

La instalación de Stow cambia ligeramente según la plataforma, pero en general es tremendamente directa. En macOS, lo habitual es usar Homebrew, el gestor de paquetes más extendido en este sistema:

brew install stow

En distribuciones Linux como Debian o Ubuntu, lo normal es tirar de apt:

sudo apt install stow

En Arch Linux y derivadas, lo encuentras en los repos oficiales y se instala con pacman sin mayor misterio:

sudo pacman -S stow

Una vez instalado, dispones del comando “stow” en tu PATH. No hay demonios ni servicios de fondo, simplemente un binario que se ejecuta cuando lo necesitas. Puedes comprobar que todo está correcto con un “stow –version” y listo.

En equipos donde ya usas herramientas como Oh My Zsh, Stow encaja muy bien: puedes mantener tanto el .zshrc como la configuración de plugins y temas en tu repo central y aplicar todo con un par de comandos. Muchos usuarios con varios Mac o con mezcla de Linux y macOS comentan que así consiguen tener la misma shell y el mismo prompt en todas partes.

Ignorar archivos no deseados con .stow-local-ignore

Uno de los detalles finos de Stow es el sistema de ignore. Por defecto, Stow ya ignora ciertos archivos típicos de control de versiones como .git, .gitignore, .gitmodules, directorios de CVS, RCS, etc. Sin embargo, hay situaciones donde necesitas un control más específico, por ejemplo en macOS con los infames .DS_Store.

Stow permite crear un fichero llamado .stow-local-ignore en el directorio desde el que ejecutas el comando. Ese archivo define qué patrones deben ser ignorados a nivel local. En el momento en que lo creas, dejas de usar la lista de ignorados por defecto, así que tienes que volver a incluirlos tú mismo y añadir los extras.

Un ejemplo típico de contenido de .stow-local-ignore incluiría comentarios y patrones para conflictos de CVS, copias de seguridad de Emacs, ficheros de control de versiones y al final .DS_Store para que Stow no se queje ni intente enlazar esos ficheros generados por Finder:

# Comentarios y líneas en blanco permitidas
RCS
.+,v
CVS
\.#.+
\.cvsignore
\.svn
_darcs
\.hg
\.git
\.gitignore
\.gitmodules
.+~
\#.*\#
^/README.*
^/LICENSE.*
^/COPYING
.DS_Store

Gracias a esto, evitas que Stow intente crear enlaces de archivos completamente irrelevantes y te ahorras errores molestos a la hora de stowear o destowear paquetes. Es especialmente útil si navegas mucho tu repo con interfaces gráficas que generan ficheros auxiliares.

Recuerda que el ignore de Stow es independiente del .gitignore que uses en tu repositorio: el primero controla qué se enlaza, el segundo qué se versiona. Entre ambos puedes afinar muy bien el comportamiento tanto de Stow como de Git.

Uso básico de Stow: enlazar y desenlazar paquetes de configuración

Con todo preparado, la operativa diaria de Stow es muy concisa. Siempre debes ejecutar Stow desde dentro del directorio de tu repo de dotfiles, no desde tu $HOME ni desde rutas arbitrarias, para que las rutas relativas que genere tengan sentido.

Imagina que ya tienes un módulo llamado “ghostty” en ~/dotfiles/ghostty/.config/ghostty con tu archivo de configuración. Una vez ubicado en el repo, puedes stowearlo con:

cd ~/dotfiles
stow ghostty

Este comando hace que en tu sistema aparezcan enlaces simbólicos desde ~/.config/ghostty a los archivos que viven en ~/dotfiles/ghostty/.config/ghostty. Si haces un “ls -l ~/.config/ghostty” verás setas (->) indicando el objetivo de cada symlink, confirmando que todo está correctamente enlazado.

Si optas por un enfoque unificado y quieres enlazarlo todo de golpe, puedes ejecutar “stow .” desde la raíz del repo. Stow interpretará cada subdirectorio como un paquete o directamente trabajará sobre la estructura si la tienes plana, y creará symlinks para todo lo que encaje.

Para revertir un paquete concreto, basta con llamar a Stow con la opción -D (de “delete” en la jerga de la herramienta). Por ejemplo:

cd ~/dotfiles
stow -D ghostty

Eso elimina los symlinks que había creado para ese módulo sin tocar los ficheros originales que siguen en el repositorio. Es una manera muy limpia de “desinstalar” configuraciones de una máquina concreta sin perderlas del todo.

Es crucial evitar un error muy común: no ejecutes Stow desde el $HOME ni desde otras carpetas externas al repo. Si lo haces, corres el riesgo de que genere enlaces en lugares inesperados y acabes con tu directorio personal lleno de cosas donde no tocan. Siempre: cd al repositorio, luego stow.

Integrar Git y GitHub en tu flujo de dotfiles con Stow

La gracia de todo este tinglado es combinar Stow con Git para que tus dotfiles estén versionados, respaldados en remoto y sean fácilmente replicables en otras máquinas. El proceso es muy directo y no difiere de cualquier otro proyecto que gestiones con Git.

Desde tu carpeta de dotfiles, inicializa un nuevo repositorio si aún no lo has hecho:

cd ~/dotfiles
git init

A partir de ahí puedes añadir tus archivos, hacer commits y trabajar con ramas como de costumbre. Un posible arranque podría ser:

git add .
git commit -m "Primer commit de mis dotfiles"

Lo siguiente suele ser crear un repositorio en GitHub, GitLab u otro servicio y añadirlo como remoto. Algo del estilo:

git remote add origin git@github.com:tuusuario/dotfiles.git
git push -u origin main

Ten en cuenta que, aunque haya quien publique sus dotfiles en repos públicos, lo más prudente es usar repos privados si manejas datos sensibles o rutas que puedan revelar demasiada información personal. En cualquier caso, puedes complementar esto con cifrado externo para secretos si fuera necesario.

Para afinar qué se versiona, conviene tener también un .gitignore en el repo donde añadas, por ejemplo, .DS_Store u otros ficheros que no quieras subir. Stow ya ignora .git de por sí, pero Git no sabe nada de .stow-local-ignore, por lo que los dos ficheros sirven a propósitos diferentes y se complementan bien.

El día a día queda muy claro: clonas tu repo de dotfiles en un nuevo equipo, instalas Stow, ejecutas “stow .” o “stow paquete1 paquete2…” y ya tienes tu entorno replicado. Si más tarde cambias tu configuración de Neovim o tu .zshrc, haces commit y push, y en el resto de máquinas basta con un git pull seguido de stow para actualizar enlaces si has añadido nuevos archivos o paquetes.