chezmoi : gérer et synchroniser ses configurations
chezmoi gère les configurations personnelles des terminaux, éditeurs et outils en ligne de commande, puis permet d’en retrouver les parties utiles sur d’autres machines. On appelle souvent ces fichiers dotfiles, car nombre de fichiers de configuration Unix commencent par un point, comme .bashrc ou .gitconfig. Ce terme inclut aussi les fichiers ordinaires du répertoire .config.
Supposons que deux ordinateurs utilisent le même thème de terminal, mais des tailles de police différentes. Git peut conserver l’historique des modifications ; il reste à décider où placer les fichiers, quelles valeurs dépendent de la machine et si l’état écrit par les applications doit être partagé. chezmoi applique ces choix aux fichiers locaux. Git assure l’historique et le transfert entre machines.
Distinguer la source du fichier utilisé par l’application
Dans son mode fichier par défaut, chezmoi ne crée pas systématiquement des liens symboliques vers le dépôt. Il calcule les fichiers attendus à partir des sources, puis met à jour leur destination. Le guide de démarrage officiel utilise ~/.local/share/chezmoi comme répertoire source par défaut ; cet emplacement est configurable.
Ainsi, chezmoi edit modifie la source, chezmoi diff compare le résultat attendu au fichier réel, et chezmoi apply modifie ce dernier. Enregistrer une source ne change donc pas immédiatement la configuration de l’application.
Installation
Choisissez la méthode adaptée à votre système parmi celles de la page officielle. Ce sont des alternatives, pas des étapes à enchaîner :
Omarchy propose aussi sa propre commande : omarchy pkg add chezmoi. Exécutez ensuite chezmoi --version pour vérifier que l’outil est disponible. Les exemples locaux ci-dessous ont été vérifiés avec chezmoi 2.72.1 ; les versions distribuées peuvent varier. Les commandes Shell utilisent la syntaxe POSIX d’un terminal Linux, macOS ou WSL, et non celle de PowerShell.
Essayer avec un petit fichier
Cet exemple suppose que chezmoi n’est pas encore configuré et que le fichier de démonstration n’existe pas. Si vous utilisez déjà l’outil, sautez l’initialisation et choisissez un chemin libre plutôt que d’écraser une configuration existante.
chezmoi init
mkdir -p ~/.config/chezmoi-demo
printf 'theme = "dark"\n' > ~/.config/chezmoi-demo/settings.toml
chezmoi add ~/.config/chezmoi-demo/settings.toml
init crée le dépôt source local. add prend en charge le fichier choisi, sans l’envoyer sur un serveur. Ouvrez maintenant la source, remplacez dark par light, enregistrez et fermez l’éditeur :
chezmoi edit ~/.config/chezmoi-demo/settings.toml
Examinez les changements avant de les appliquer :
chezmoi diff ~/.config/chezmoi-demo/settings.toml
chezmoi apply --dry-run --verbose ~/.config/chezmoi-demo/settings.toml
chezmoi apply ~/.config/chezmoi-demo/settings.toml
Le fichier réel devrait désormais contenir theme = "light". La même commande diff ne devrait plus afficher de différence. apply modifie les fichiers ; leur prise en compte immédiate dépend de l’application. Il peut être nécessaire de recharger sa configuration ou de la redémarrer.
Pour retrouver le répertoire source ou la source d’un fichier précis :
chezmoi source-path
chezmoi source-path ~/.config/chezmoi-demo/settings.toml
chezmoi managed
Quand l’application réécrit sa configuration
Certaines applications rangent dans un même fichier leurs préférences — thème, modèle par défaut — et leur état local : projets récents, position des fenêtres ou décisions de confiance. Partager tout le fichier transporte cet état avec les réglages. Un lien symbolique vers Git permet aussi à l’application de modifier directement le dépôt.
chezmoi gère les fichiers entiers par défaut. Le prochain apply peut donc écraser les changements effectués par l’application. Changer de gestionnaire ne détermine pas automatiquement quels champs doivent être communs à toutes les machines.
Pour ne partager que quelques réglages, utilisez un modèle modify_. Il reçoit le contenu actuel du fichier, modifie les champs choisis, puis produit le résultat.
Ne gérer que le thème de l’exemple
Reprenez le fichier TOML ordinaire de la section précédente. Renommez sa source en lui ajoutant le préfixe modify_. Demander le chemin réel évite de deviner les noms de répertoires utilisés par chezmoi :
source_file="$(chezmoi source-path ~/.config/chezmoi-demo/settings.toml)"
mv "$source_file" "$(dirname "$source_file")/modify_$(basename "$source_file")"
chezmoi edit ~/.config/chezmoi-demo/settings.toml
Remplacez le contenu ouvert dans l’éditeur par le modèle suivant. Il s’agit d’un modèle chezmoi, pas du TOML que l’application lira :
{{/* chezmoi:modify-template */}}
{{- $config := .chezmoi.stdin | fromToml -}}
{{- $before := $config | toJson -}}
{{- $config = setValueAtPath "theme" "light" $config -}}
{{- if eq $before ($config | toJson) -}}
{{ .chezmoi.stdin }}
{{- else -}}
{{ $config | toToml }}
{{- end -}}
Le marqueur de la première ligne active le traitement comme modèle de modification. N’ajoutez pas de suffixe .tmpl à ce type de fichier. .chezmoi.stdin contient le fichier actuel, fromToml l’analyse et setValueAtPath ne règle que theme. Si la valeur convient déjà, le modèle renvoie le texte original pour éviter de modifier inutilement la présentation.
Simulez ensuite l’enregistrement d’un projet récent par l’application :
printf '\nrecent_project = "/example/project"\n' >> ~/.config/chezmoi-demo/settings.toml
chezmoi diff ~/.config/chezmoi-demo/settings.toml
chezmoi apply ~/.config/chezmoi-demo/settings.toml
Le thème étant déjà light, diff devrait rester vide et recent_project rester dans le fichier local. Le dépôt source conserve la règle du thème, pas cette entrée de projet. Si l’application remet le thème à dark, le prochain apply rétablit light tout en conservant les valeurs des autres champs.
Cet exemple ne sérialise à nouveau le TOML que lorsqu’un champ géré change ; les commentaires et la mise en forme peuvent alors être perdus. Si les commentaires doivent être conservés exactement, choisissez un outil d’édition qui les préserve, ou utilisez les mécanismes include et de surcharge locale de l’application. Pour migrer une vraie configuration déjà gérée par lien symbolique, sauvegardez-la et détachez l’ancien lien avant la migration, afin que deux outils ne gèrent pas le même chemin.
Des valeurs différentes selon la machine
Pour une configuration entièrement maintenue par vous, sans réécriture par l’application, utilisez un modèle ordinaire. Ajoutez le fichier pour la première fois avec chezmoi add --template CHEMIN, puis ouvrez-le avec chezmoi edit CHEMIN.
Les modèles peuvent lire le système via .chezmoi.os, ou des valeurs personnalisées sous [data] dans le fichier local ~/.config/chezmoi/chezmoi.toml. Le modèle d’une application fictive pourrait contenir :
font_size = {{ if eq .chezmoi.os "darwin" }}14{{ else }}12{{ end }}
Cela donne 14 sur macOS et 12 ailleurs. Ce n’est qu’un exemple de condition : Windows et WSL peuvent aussi utiliser des emplacements différents, et remplacer une valeur ne rend pas toutes les applications compatibles entre systèmes.
Un modèle ordinaire génère tout le fichier ; un modèle modify_ part du fichier existant. Choisissez la méthode adaptée à chaque destination. Ne réajoutez pas le modèle de modification précédent comme un fichier .tmpl ordinaire.
Retrouver sa configuration sur une autre machine avec Git
Lorsque le dépôt source ne contient que les configurations non sensibles à partager, suivez le parcours officiel entre machines. Créez un dépôt privé vide nommé dotfiles chez votre hébergeur Git, puis entrez dans le répertoire source de chezmoi :
chezmoi cd
Cette commande ouvre un sous-shell. Exécutez-y les commandes suivantes en remplaçant YOUR_USER par votre compte. Si un dépôt distant est déjà défini, n’ajoutez pas origin une seconde fois :
git status --short
git add .
git diff --cached
git commit -m "Manage example app settings"
git remote add origin git@github.com:YOUR_USER/dotfiles.git
git push -u origin HEAD
exit
Même privé, un dépôt n’est pas un emplacement pour les mots de passe, cookies, clés privées ou fichiers d’authentification. Ne validez que les configurations non sensibles choisies, sans importer tout le répertoire personnel ou celui d’une application.
Sur une autre machine où chezmoi n’est pas encore configuré, installez l’outil et assurez l’accès au dépôt, puis séparez l’initialisation de l’application :
chezmoi init git@github.com:YOUR_USER/dotfiles.git
chezmoi diff
chezmoi apply --dry-run --verbose
chezmoi apply
Utilisez un dépôt source que vous contrôlez ou avez examiné : un dépôt chezmoi peut également contenir des scripts exécutables. Lire les premières différences, plutôt que lancer directement init --apply, aide à repérer les incompatibilités de plateforme et les conflits avec les réglages existants.
Pour les mises à jour suivantes, récupérez les changements avant de décider de les appliquer :
chezmoi git -- pull --ff-only
chezmoi diff
chezmoi apply
Si Git signale une divergence ou des modifications locales en conflit, traitez les différences au lieu de forcer l’écrasement. Le raccourci chezmoi update récupère et applique les changements par défaut ; son appel Git par défaut utilise aussi autostash et rebase. Ce n’est donc pas une simple commande de téléchargement.
Par quels fichiers commencer ?
Choisissez un ou deux petits fichiers sans secrets, dont les changements sont faciles à comprendre. Les thèmes de terminal et raccourcis d’éditeur conviennent à un premier essai de gestion complète. Pour les fichiers contenant des projets récents, des décisions de confiance ou l’état des fenêtres, choisissez d’abord les champs gérés, puis écrivez un modèle de modification. Si l’application permet déjà de combiner des réglages communs avec des surcharges locales, privilégiez cette organisation.
Il n’est pas nécessaire de migrer tous les outils à la fois, ni d’écrire un système général de synchronisation. Pour chaque nouveau fichier, précisez les valeurs à partager, celles à garder localement et ce que le prochain apply changera.