dotfiles-Verwaltung — chezmoi vs. yadm vs. rohe Symlinks, Mac-Edition

Wer .zshrc, .gitconfig und ~/.config/...-Dateien bei jedem neuen Mac noch manuell kopiert, braucht ein dotfiles-Verwaltungs-Tool. Einmal eingerichtet, stellt ein neues Gerät die vollständige Konfiguration mit einem einzigen Befehl wieder her.

Dieser Leitfaden vergleicht drei Ansätze (chezmoi · yadm · rohe Symlinks + Git) und geht das empfohlene chezmoi-Setup im Detail durch.

TL;DR

1. Warum ein dotfiles-Tool

.zshrc direkt in einem Git-Repo ablegen und verlinken funktioniert. Aber diese Probleme häufen sich:

• Maschinenspezifische Unterschiede: git user.email des Arbeits-Macs vs. privat — die Verzweigung endet hart kodiert.
• Secrets: API-Schlüssel / SSH-Konfig gemeinsam ablegen ist riskant — .gitignore wird leicht vergessen.
• Bidirektionalität: Wer ~/.zshrc direkt bearbeitet, lässt das Repo driften und verliert den Überblick, was die Wahrheitsquelle ist.
• Neues Gerät: Clone → Abhängigkeiten installieren → Symlinks setzen → Berechtigungen anpassen… jedes Mal von vorn.

Ein dotfiles-Tool verpackt das in einen einheitlichen Workflow.

2. Optionen im Vergleich

chezmoi

Go-basiertes CLI. Template-Engine (maschinenspezifische Verzweigung), Secrets (1Password / Bitwarden Integration), bidirektional (chezmoi diff / chezmoi apply).

yadm

Ein Git-Wrapper, der dotfiles in ~ als direktes Git-Repository behandelt. Null Lernaufwand. Maschinenspezifische Verzweigung wird unterstützt, ist aber begrenzt (Alt-Dateien wie .zshrc##os.Darwin).

Rohe Symlinks + Git

Dateien in ~/dotfiles/ ablegen und mit einem Installationsskript verlinken. Transparenteste, aber du implementierst jede Funktion selbst.

Empfehlung: chezmoi

Für eine einzelne Person mit 1–3 Geräten ist chezmoi die klare Wahl. Eine Stunde Lernaufwand zahlt sich lebenslang aus.

3. chezmoi-Setup

3.1 Installieren

brew install chezmoi

3.2 GitHub-Repo vorbereiten

Ein privates dotfiles-Repo auf GitHub erstellen (der Name ist deine Wahl). Leer ist in Ordnung.

3.3 chezmoi initialisieren

chezmoi init github.com/yourname/dotfiles
# Oder, wenn SSH verfügbar:
chezmoi init git@github.com:yourname/dotfiles.git

~/.local/share/chezmoi/ wird zum Arbeitsbaum — das eigentliche Git-Repo.

3.4 Dateien hinzufügen

# .zshrc unter chezmoi-Verwaltung stellen
chezmoi add ~/.zshrc
 
# Oder mehrere auf einmal
chezmoi add ~/.gitconfig ~/.tmux.conf ~/.config/starship.toml

Dateien werden als ~/.local/share/chezmoi/dot_zshrc kopiert (führender Punkt → dot_-Präfix).

3.5 Commit + Push

chezmoi cd          # zum Arbeitsbaum springen
git add .
git commit -m "init dotfiles"
git push -u origin main
exit                # zurück zum ursprünglichen Ort

3.6 Auf einem neuen Gerät wiederherstellen

# Auf dem neuen Mac
brew install chezmoi
chezmoi init --apply github.com/yourname/dotfiles

Fertig. Alle dotfiles materialisieren sich in ~ und sind sofort wirksam.

4. Maschinenspezifische Verzweigung (Templates)

chezmois stärkste Funktion: Dasselbe .gitconfig passt sich an Arbeit und Privat an:

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

Inhalt:

[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

Die .tmpl-Erweiterung markiert ein Template. chezmoi verzweigt beim Anwenden basierend auf dem Hostnamen.

4.1 Verfügbare Variablen

chezmoi data       # alle Kontextvariablen ausgeben

Häufig verwendet:

• .chezmoi.os — darwin / linux / windows
• .chezmoi.hostname — Gerätename
• .chezmoi.arch — arm64 / amd64
• Benutzerdefiniert — mit chezmoi edit-config hinzufügen

4.2 OS-spezifische Dateien

dot_zshrc in dot_zshrc.tmpl umbenennen und nach OS verzweigen:

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

5. Secrets-Integration

API-Schlüssel und Token niemals direkt in dotfiles schreiben. Stattdessen chezmois Secret-Tool-Integration verwenden:

1Password CLI

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 mit Secrets-Referenzen:

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

Bei chezmoi apply werden die Werte aus 1Password abgerufen und in eine Klartext-.env geschrieben. Diese Datei ist per .gitignore ausgeschlossen und gelangt daher nie ins Repo.

Bitwarden / pass / age

Jedes hat eine offizielle chezmoi-Integration — siehe docs.chezmoi.io.

6. Workflow

Täglich

# Nach direkter Bearbeitung von ~/.zshrc
chezmoi diff       # sehen, was sich geändert hat
chezmoi add ~/.zshrc   # zurück ins Repo propagieren
chezmoi cd && git commit -am "tweak zshrc" && git push

Ein weiteres Gerät synchronisieren

chezmoi update     # git pull + apply

Änderungen vorschauen

chezmoi diff       # Änderungen vor dem Anwenden
chezmoi apply -v   # ausführliches Anwenden

Quelle bearbeiten

chezmoi edit ~/.zshrc   # Quelle (= Repo) bearbeiten und automatisch anwenden

7. yadm — die leichteste Alternative

Wenn null Lernaufwand deine Priorität ist, 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
 
# Anderes Gerät
yadm clone git@github.com:yourname/dotfiles.git

Befehle sind identisch mit git (nur die Binärdatei unterscheidet sich). Nachteil: maschinenspezifische Verzweigung ist auf Alt-Dateien wie .zshrc##os.Darwin beschränkt.

8. Rohe Symlinks + Git

Minimale Abhängigkeiten:

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

Transparent und ohne Abhängigkeiten — aber Secrets, Verzweigung und Bootstrap müssen selbst implementiert werden. Die meisten wechseln innerhalb eines Jahres zu chezmoi.

Wie verifizieren

1. chezmoi diff → keine Änderungen (alles angewendet)
2. ~/.zshrc direkt bearbeiten → chezmoi diff zeigt den Diff
3. Auf einem neuen Gerät (oder sauberer VM) chezmoi init --apply github.com/you/dotfiles → alle dotfiles wiederhergestellt
4. Nach Änderung eines Templates, chezmoi apply -v → unterschiedliche Ausgabe je nach Hostname
5. Mit 1Password-Integration schreibt chezmoi apply Klartext in ~/.env, aber das Repo enthält es nicht

Problembehandlung

chezmoi apply ändert nichts

• chezmoi diff prüfen. Wenn die Ausgabe leer ist, ist das erwartetes Verhalten.
• Unterschiede in Datei-Berechtigungen können Änderungen verbergen — chezmoi apply --force versuchen.

Template-Syntaxfehler

{{ ... }} sind Go-Templates. Fehlende abschließende -}} und Tippfehler bei Variablennamen sind häufige Fehlerquellen. Trockenlauf mit chezmoi execute-template < dot_gitconfig.tmpl.

1Password-Integration schlägt fehl

• Nach op signin ist die Sitzung standardmäßig ~30 Minuten gültig. eval $(op signin) erneut ausführen.
• 1Password explizit in chezmoi.toml aktivieren (chezmoi edit-config).

SSH-Schlüssel auf neuem Gerät fehlen

SSH-Schlüssel niemals in dotfiles selbst speichern (Sicherheitsrisiko). Auf dem neuen Gerät neue Schlüssel generieren und bei GitHub registrieren. chezmoi verwaltet nur Konfigurationsdateien wie ~/.ssh/config.

~/.zshrc wird durch direkte Bearbeitung nicht aktualisiert

chezmoi edit ~/.zshrc verwenden (bearbeitet Quelle, wendet automatisch an). Oder Quelle direkt bearbeiten und chezmoi apply.

Referenzen

• Mac-Ersteinrichtung — Homebrew usw. vor dotfiles
• Mac↔Win Datei-Synchronisierung — Syncthing für Notizen/Projekte, separat von dotfiles
• chezmoi (offiziell)
• yadm

Changelog

• 2026-05-12: Erster Entwurf. Drei Ansätze im Vergleich + chezmoi praktisches Setup (Templates / Secrets / Workflow) + fünf Problembehandlungsfälle.