Dotfiles avec GNU Stow

Documentation d'utilisation de GNU Stow pour gérer les dotfiles via des liens symboliques.

Principe

Stow gère des « paquets » (packages) : chaque sous-dossier de votre répertoire de dotfiles représente un logiciel (bash, git, vim...), et reproduit l'arborescence qu'il faudrait avoir depuis $HOME. Stow crée ensuite des liens symboliques depuis $HOME vers ces fichiers.

dotfiles/
├── bash/
│   └── .bashrc
├── git/
│   └── .config/
│       └── git/
│           └── config
└── vim/
    └── .vimrc

En lançant stow bash depuis dotfiles/, Stow crée ~/.bashrc -> dotfiles/bash/.bashrc.

Installation

sudo apt install stow

Structure recommandée

~/dotfiles/
├── <nom_du_paquet>/
│   └── <chemin_relatif_a_HOME>

Chaque paquet doit reproduire fidèlement la structure attendue sous $HOME (y compris les dossiers .config/...).

Commandes de base

Toutes les commandes s'exécutent depuis le répertoire des dotfiles (le « dossier stow »), et ciblent $HOME par défaut.

Installer (créer les liens) un paquet

cd ~/dotfiles
stow bash

Installer plusieurs paquets

stow bash git vim

Désinstaller (supprimer les liens) un paquet

stow -D bash

Réinstaller (utile après modification de la structure d'un paquet)

stow -R bash

Simulation (dry-run), sans rien modifier

stow -n -v bash

-v (verbose) peut être répété (-vv, -vvv) pour plus de détails.

Options utiles

Option	Effet
-n	Simulation, n'effectue aucune action
-v	Verbeux (cumulable)
-D	Supprime les liens (unstow)
-R	Restow = -D puis stow (utile après un git pull)
-t <dir>	Change le dossier cible (défaut $HOME)
-d <dir>	Change le dossier source des paquets (défaut le dossier courant)
--adopt	Rapatrie les fichiers déjà existants dans la cible vers le paquet, au lieu d'échouer
--ignore=<regex>	Ignore certains fichiers/motifs

Exemple avec cibles explicites

stow -d ~/dotfiles -t ~ bash

Gérer un conflit (fichier déjà existant)

Si ~/.bashrc existe déjà en tant que fichier réel (pas un lien), Stow refuse d'écraser :

* existing target is not a symlink: .bashrc

Deux solutions :

1. Sauvegarder puis remplacer par le paquet

mv ~/.bashrc ~/.bashrc.bak
stow bash

2. Laisser Stow récupérer le fichier existant dans le paquet

stow --adopt bash

⚠️ Cette option écrase le contenu du paquet avec celui du fichier existant : vérifiez ensuite avec git diff qu'aucune modification indésirable n'a été introduite.

3. Utiliser --no-folding (recommandé pour les fichiers existants) Si tu veux que Stow ne remplace pas les fichiers existants dans ~/.ssh (comme config ou config.d/ovh.config), utilise l'option --no-folding pour éviter de supprimer les fichiers déjà présents. Commande :

stow --no-folding -S ssh

• Effet : Stow va créer des liens symboliques pour les fichiers manquants dans ~/.ssh, mais ignorera ceux qui existent déjà.
• Limite : Si un fichier existe déjà dans ~/.ssh (ex: config), Stow ne le liera pas depuis dotfiles/ssh/.ssh/config.

Ajouter un nouveau paquet

1. Créer le dossier avec la structure relative à $HOME :

   mkdir -p ~/dotfiles/tmux
   mv ~/.tmux.conf ~/dotfiles/tmux/.tmux.conf
   

2. Lancer Stow :

   cd ~/dotfiles
   stow tmux
   

Vérifier l'état des liens

ls -la ~ | grep dotfiles

Les liens créés par Stow pointent vers le chemin absolu ou relatif du paquet source.

Bonnes pratiques

• Versionner ~/dotfiles/ avec Git.
• Un paquet = un logiciel/outil, pour pouvoir (dés)installer indépendamment.
• Utiliser stow -R après un git pull pour prendre en compte d'éventuels fichiers ajoutés/supprimés.
• Toujours tester avec -n -v avant une opération sur une nouvelle machine.
• Ne pas mélanger dans un paquet des fichiers destinés à des cibles différentes (utiliser -t par machine/contexte si besoin, ou des paquets séparés type bash-perso / bash-travail).

Dépannage

Symptôme	Cause probable	Solution
existing target is not a symlink	Fichier réel déjà présent dans $HOME	Sauvegarder ou --adopt
existing target is not owned by stow	Lien symlink présent mais ne pointant pas vers le dossier stow	Vérifier avec stow -n -v, supprimer le lien orphelin si besoin
Rien ne se passe après modif d'un paquet	Les liens existants ne sont pas mis à jour automatiquement pour les nouveaux fichiers	Relancer stow -R <paquet>
Symlinks cassés après déplacement du dossier dotfiles	Chemin source invalide	Relancer stow -R depuis le nouvel emplacement

Ressources

• Manuel officiel : man stow
• Site du projet : https://www.gnu.org/software/stow/

---

Sous-modules Git

Principe

Un sous-module Git permet d'inclure un dépôt Git à l'intérieur d'un autre, tout en gardant chacun son propre historique indépendant. Le dépôt parent ne stocke que :

• l'URL du sous-module (dans .gitmodules),
• le chemin où il est monté,
• un pointeur figé vers un commit précis du sous-module (pas une branche suivie en continu).

Cas d'usage typiques :

• Partager une brique commune (bibliothèque, template, thème) entre plusieurs projets.
• Séparer des dotfiles publics et un dépôt privé (ex. dotfiles/secrets en sous-module d'un dotfiles public).
• Isoler des fichiers volumineux ou à cycle de vie différent (ex. gendoc/ versionné à part du projet principal).

Commandes de base

Ajouter un sous-module

git submodule add <url> <chemin>
git commit -m "Ajout du sous-module <chemin>"

Cloner un dépôt contenant des sous-modules

git clone --recurse-submodules <url>
# ou, si déjà cloné sans l'option :
git submodule update --init --recursive

Mettre à jour un sous-module vers son dernier commit distant

cd <chemin_du_sous_module>
git pull origin main
cd -
git add <chemin_du_sous_module>
git commit -m "Mise à jour du sous-module <chemin> vers <hash>"

Voir l'état des sous-modules

git submodule status

Le caractère devant le hash indique l'état :

• (rien) : synchronisé avec le commit enregistré.
• + : le sous-module pointe vers un commit différent de celui enregistré dans le parent.
• - : le sous-module n'est pas initialisé.

Mettre à jour tous les sous-modules d'un coup

git submodule update --remote --merge

Points de vigilance

• Un git pull sur le dépôt parent ne met pas à jour le contenu des sous-modules automatiquement ; il faut git submodule update.
• Le pointeur enregistré dans le parent est un commit précis, jamais une branche : penser à committer le parent après chaque mise à jour de sous-module, sinon le changement est perdu.
• Éviter de travailler directement dans un sous-module sans être sur une branche (état detached HEAD par défaut après un clone) ; sinon git checkout -b <branche> avant de committer.
• Supprimer proprement un sous-module nécessite plusieurs étapes (git submodule deinit, suppression dans .gitmodules, git rm, suppression dans .git/modules/) — il n'y a pas de commande unique.

---

Cas d'usage : mettre à jour un sous-module vers une version de référence

Objectif : faire pointer le sous-module (par exemple workflow-inc-release-hotfix) vers un commit, un tag, ou une branche précis — c'est-à-dire changer la « version de référence » enregistrée dans le dépôt parent.

Étapes

1. Se placer dans le sous-module et récupérer les références distantes

   cd workflow-inc-release-hotfix
   git fetch --all --tags
   

2. Se positionner sur la version de référence voulue

   Vers un tag :

   git checkout vX.Y.Z
   

   Vers une branche (ex. main, hotfix/...) :

   git checkout main
   git pull
   

   Vers un commit précis :

   git checkout <hash>
   

3. Revenir dans le dépôt parent et enregistrer le nouveau pointeur

   cd ..
   git add workflow-inc-release-hotfix
   git commit -m "Bump workflow-inc-release-hotfix -> vX.Y.Z"
   

C'est cette étape 3 qui compte : git add sur le chemin du sous-module enregistre dans le parent le commit exact vers lequel il pointe désormais. Sans ce commit, le changement de version n'est pas conservé.

Vérifier la version actuellement référencée

git submodule status workflow-inc-release-hotfix

Affiche le hash du commit enregistré dans le parent (précédé de + si le sous-module local pointe ailleurs que ce hash, ou de - s'il n'est pas initialisé).

Raccourci pour mettre à jour vers le dernier commit distant d'une branche suivie

git submodule update --remote workflow-inc-release-hotfix
git add workflow-inc-release-hotfix
git commit -m "Mise à jour workflow-inc-release-hotfix vers le dernier commit"

Ceci suppose que .gitmodules définit une branch à suivre pour ce sous-module ; sinon, --remote ne fonctionne pas et il faut utiliser la méthode manuelle ci-dessus.