Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 13: Dotfiles und neuer Mac

Ziel: Deine Konfiguration liegt versioniert in chezmoi, ein neuer Mac ist in einer Stunde einsatzbereit. · Dauer: ca. 120 min · Voraussetzung: Tag 12

Briefing

  • chezmoi verwaltet Dotfiles in einem Quellverzeichnis (Git-Repo) und schreibt sie per apply ins Home. Templates kennen den Rechner: Arbeit oder privat, Hostname, Architektur.
  • Secrets landen nie im Repo. Templates holen sie zur Laufzeit aus 1Password (op) oder dem macOS-Schlüsselbund.
  • Brewfile + brew bundle beschreibt alle Pakete, ein defaults-Skript die macOS-Einstellungen, ein Bootstrap-Skript verbindet alles.
  • Alle Drills laufen in ~/term-lab/cz. Deine echte ~/.local/share/chezmoi und dein echtes Home fasst du heute nicht an.
Git-Repo (Quelle)        chezmoi apply          Home (Ziel)
dot_zshrc          ───────────────────────►  ~/.zshrc
dot_gitconfig.tmpl ── Template + Daten ────►  ~/.gitconfig
Brewfile           ── run_onchange-Skript ─►  brew bundle

Drill 1: Übungsgelände für chezmoi

chezmoi kennt Flags für Quelle, Ziel, Konfig, State und Cache. Eine Funktion cz biegt alle fünf in die Sandbox um. Starte zuerst die Übungs-Shell mit ~/term-lab/lab.

mkdir -p ~/term-lab/cz/{src,home,cfg}
cat > ~/term-lab/config/zsh/cz-lab.zsh <<'EOF'
# chezmoi im Übungsgelände: echte ~/.local/share/chezmoi bleibt unberührt
CZ_LAB="$LAB/cz"
cz() {
  chezmoi --source "$CZ_LAB/src" --destination "$CZ_LAB/home" \
    --config "$CZ_LAB/cfg/chezmoi.toml" \
    --persistent-state "$CZ_LAB/cfg/state.boltdb" \
    --cache "$CZ_LAB/cfg/cache" "$@"
}
EOF
source ~/term-lab/config/zsh/cz-lab.zsh
cz init
cz source-path
ls -a ~/term-lab/cz/src

Erwartet:

/Users/<du>/term-lab/cz/src
.   ..  .git

Achtung: Ohne die Flags arbeitet chezmoi auf ~/.local/share/chezmoi und deinem echten Home. Tippe heute immer cz, nie chezmoi.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Dateien übernehmen – add, edit, diff, apply

Lege ein Mini-Home an und übernimm drei Dateien. add kopiert ins Quellverzeichnis, das Ziel bleibt unverändert.

H=~/term-lab/cz/home
mkdir -p $H/.config/zsh
printf 'export EDITOR=nvim\nsource ~/.config/zsh/aliases.zsh\n' > $H/.zshrc
printf "alias ll='eza -l'\n" > $H/.config/zsh/aliases.zsh
cz add $H/.zshrc $H/.config/zsh/aliases.zsh
find ~/term-lab/cz/src -path '*/.git' -prune -o -type f -print
cz managed

Erwartet:

/Users/<du>/term-lab/cz/src/dot_zshrc
/Users/<du>/term-lab/cz/src/dot_config/zsh/aliases.zsh
.config
.config/zsh
.config/zsh/aliases.zsh
.zshrc

Warum? Präfixe im Dateinamen tragen die Metadaten: dot_ wird zu ., später kommen private_, executable_ und die Endung .tmpl dazu.

Jetzt änderst du die Quelle, prüfst den Unterschied und rollst aus. Im Alltag öffnet cz edit $H/.config/zsh/aliases.zsh deinen $EDITOR. Hier geht es ohne Editor.

echo "alias k=kubectl" >> "$(cz source-path $H/.config/zsh/aliases.zsh)"
cz status
cz diff --no-pager
cz apply -v --no-pager >/dev/null
cat $H/.config/zsh/aliases.zsh

Erwartet:

 M .config/zsh/aliases.zsh
diff --git a/.config/zsh/aliases.zsh b/.config/zsh/aliases.zsh
@@ -1 +1,2 @@
 alias ll='eza -l'
+alias k=kubectl
alias ll='eza -l'
alias k=kubectl

Der umgekehrte Weg: Jemand (du) ändert das Ziel direkt. status zeigt dann MM, re-add holt die Änderung zurück in die Quelle.

echo "export PAGER=less" >> $H/.zshrc
cz status
cz re-add && cz status && echo "sauber"

Erwartet:

MM .zshrc
sauber
Befehl Wirkung Merkhilfe
cz add <ziel> Ziel → Quelle kopieren aufnehmen
cz edit <ziel> Quelle im Editor öffnen nie das Ziel editieren
cz diff / cz status Quelle vs. Ziel erst schauen
cz apply Quelle → Ziel schreiben dann schreiben
cz re-add geänderte Ziele zurückholen Drift einsammeln

Fortschritt speichern? Kostenlos registrieren

Drill 3: Templates pro Rechner – work oder privat

Eine Datei .chezmoi.toml.tmpl im Quellverzeichnis erzeugt beim init die Konfiguration. promptChoiceOnce fragt nur beim ersten Mal und merkt sich die Antwort.

S=~/term-lab/cz/src
cat > $S/.chezmoi.toml.tmpl <<'EOF2'
{{- $hosttype := promptChoiceOnce . "hosttype" "Rechnerart" (list "work" "privat") -}}
{{- $email := promptStringOnce . "email" "Git-E-Mail" -}}
[data]
  hosttype = {{ $hosttype | quote }}
  email = {{ $email | quote }}
EOF2
cz init --promptChoice Rechnerart=work \
  --promptString [email protected]
cat ~/term-lab/cz/cfg/chezmoi.toml

Erwartet:

[data]
  hosttype = "work"
  email = "[email protected]"

Warum die Flags? Interaktiv fragt cz init einfach nach. --promptChoice und --promptString beantworten die Fragen vorab – der Schlüssel ist der Fragetext, nicht der Variablenname.

Jetzt das Template für die Git-Konfiguration. Auf dem Arbeitsrechner kommt ein Proxy dazu.

cat > $S/dot_gitconfig.tmpl <<'EOF2'
[user]
  name = Thomas Zachmann
  email = {{ .email }}
{{- if eq .hosttype "work" }}
[http]
  proxy = http://proxy.kunde.example:3128
{{- end }}
[core]
  pager = delta
EOF2
cz execute-template \
  '{{ .chezmoi.os }}/{{ .chezmoi.arch }} {{ .chezmoi.hostname }} {{ .hosttype }}'
echo; cz cat $H/.gitconfig

Erwartet:

darwin/arm64 tzachmann-mbair work
[user]
  name = Thomas Zachmann
  email = [email protected]
[http]
  proxy = http://proxy.kunde.example:3128
[core]
  pager = delta

Rechner umwidmen: Erst die work-Version ausrollen, dann erzwingt --prompt die Fragen erneut und diff zeigt sofort die Folgen.

cz apply
cz init --prompt --promptChoice Rechnerart=privat \
  --promptString [email protected]
cz diff --no-pager | grep '^[-+] '
cz apply && cz git -- add -A && cz git -- commit -qm "Dotfiles: erste Version"
cz git -- log --oneline

Erwartet:

-  email = [email protected]
-  proxy = http://proxy.kunde.example:3128
+  email = [email protected]
65802bc Dotfiles: erste Version

Ein cz git arbeitet im Quellverzeichnis, GIT_CONFIG_GLOBAL aus Tag 10 gilt weiter.

Tipp: cz data zeigt alle Variablen, die Templates sehen. Für Tippfehler in Templates ist cz execute-template < datei.tmpl der schnellste Test.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Secrets – 1Password und Schlüsselbund

Ein Secret gehört nie ins Repo, sondern wird beim apply geholt. Das Präfix private_ setzt die Rechte auf 0600. lookPath macht das Template robust, wenn op fehlt.

mkdir -p $S/dot_config/termlab
cat > $S/dot_config/termlab/private_secrets.env.tmpl <<'EOF2'
# Erzeugt von chezmoi - nicht einchecken, nicht von Hand ändern.
{{- if lookPath "op" }}
export GITHUB_TOKEN={{ onepasswordRead "op://Private/GitHub/token" | quote }}
{{- else }}
# 1Password-CLI (op) fehlt - kein Token gesetzt.
{{- end }}
EOF2
cz apply
ls -l $H/.config/termlab
cat $H/.config/termlab/secrets.env

Erwartet (ohne installierte 1Password-CLI):

total 8
-rw-------@ 1 <du>  staff  115 10 Okt 08:35 secrets.env
# Erzeugt von chezmoi - nicht einchecken, nicht von Hand ändern.
# 1Password-CLI (op) fehlt - kein Token gesetzt.

Ohne Schutz bricht das Template hart ab – gut so, denn ein leeres Token wäre schlimmer:

cz execute-template '{{ onepasswordRead "op://Private/GitHub/token" }}'

Erwartet:

chezmoi: template: arg1:1:3: executing "arg1" at <onepasswordRead
"op://Private/GitHub/token">: error calling onepasswordRead: op signin --raw:
exec: "op": executable file not found in $PATH

Die Schlüsselbund-Variante ohne Zusatztool (nicht ausführen – sie liest deinen echten Login-Schlüsselbund):

# einmalig im Terminal ablegen (fragt das Secret ab, landet in der Keychain):
#   security add-generic-password -s termlab-github -a "$USER" -w
# im Template:
export GITHUB_TOKEN={{ keyring "termlab-github" .chezmoi.username | quote }}

Sicherheit: cz diff und cz cat zeigen gerenderte Secrets im Klartext. Nicht in geteilten Terminals oder Screencasts benutzen.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Ignorieren und Skripte – run_onchange

.chezmoiignore ist selbst ein Template: Kunden-Konfiguration landet nur auf dem Arbeitsrechner. Skripte unter .chezmoiscripts/ laufen bei apply. run_onchange_ heißt: nur, wenn sich der gerenderte Inhalt ändert – der Hash des Brewfiles im Kommentar sorgt genau dafür.

cp $BUCH/brew/Brewfile $S/Brewfile
cat > $S/.chezmoiignore <<'EOF2'
Brewfile
{{- if ne .hosttype "work" }}
.config/kunde/**
{{- end }}
EOF2
mkdir -p $S/dot_config/kunde $S/.chezmoiscripts
echo 'proxy=on' > $S/dot_config/kunde/env
cat > $S/.chezmoiscripts/run_onchange_before_10-brew.sh.tmpl <<'EOF2'
#!/bin/bash
# Läuft nur, wenn sich der Brewfile ändert.
# Brewfile-Hash: {{ include "Brewfile" | sha256sum }}
set -euo pipefail
brew bundle --file={{ joinPath .chezmoi.sourceDir "Brewfile" | quote }}
EOF2
cz ignored
cz status

Erwartet (Rechnerart privat):

.config/kunde
Brewfile
 R .chezmoiscripts/10-brew.sh

R heißt: Das Skript würde laufen. Im Lab soll es das nicht – du schaust es dir nur gerendert an und rollst ohne Skripte aus:

cz execute-template \
  < $S/.chezmoiscripts/run_onchange_before_10-brew.sh.tmpl | sed "s#$HOME#~#"
cz apply --exclude=scripts && cz status

Erwartet:

#!/bin/bash
# Läuft nur, wenn sich der Brewfile ändert.
# Brewfile-Hash: 5faf7d56a71b…
set -euo pipefail
brew bundle --file="~/term-lab/cz/src/Brewfile"
 R .chezmoiscripts/10-brew.sh

Achtung: cz apply ohne --exclude=scripts würde hier brew bundle starten und Pakete installieren. Auf einem echten neuen Mac ist genau das gewollt.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Brewfile – prüfen, erzeugen, aufräumen

Das Brewfile kennst du aus Tag 0. Heute drehst du die Richtung um: Was ist auf dem Mac installiert, was fehlt, was ist zu viel? Alle drei Befehle ändern nichts am System.

brew bundle check --verbose --no-upgrade --file=$BUCH/brew/Brewfile
brew bundle dump --file=~/term-lab/cz/Brewfile.ist
awk '{print $1}' ~/term-lab/cz/Brewfile.ist | sort | uniq -c
brew bundle cleanup --file=$BUCH/brew/Brewfile | head -4

Erwartet (gekürzt, hängt von deinem Mac ab):

brew bundle can't satisfy your Brewfile's dependencies.
→ Cask ghostty needs to be installed.
→ Formula just needs to be installed.
Satisfy missing dependencies with `brew bundle install`.
 107 #
  95 brew
  14 cask
   3 tap
Would uninstall casks:
bitwarden
dropbox
…

Warum? dump schreibt zu jedem Paket die Beschreibung als #-Kommentar dazu. cleanup ohne --force ist ein Trockenlauf und zeigt, was nicht im Brewfile steht. --no-upgrade ignoriert veraltete Versionen – sonst meldet check auch Pakete, die nur ein Update brauchen.

Befehl Wirkung Merkhilfe
brew bundle check Brewfile erfüllt? Soll = Ist?
brew bundle dump Ist-Zustand → Brewfile Inventur
brew bundle cleanup zeigt Überzähliges erst ohne --force
brew bundle --file=… installiert Fehlendes nur auf neuem Mac

Tipp: Pflege ein Brewfile im chezmoi-Repo. Rechnerspezifisches (Kunden-VPN, private Apps) trennst du mit einem Template Brewfile.tmpl und {{ if eq .hosttype "work" }}.

Fortschritt speichern? Kostenlos registrieren

Drill 7: macOS-Einstellungen als Code – defaults

Lesen ist immer erlaubt. Fehlt ein Schlüssel, gilt der Werkseinstellungswert – defaults meldet dann einen Fehler.

defaults read com.apple.finder AppleShowAllFiles
defaults read com.apple.dock autohide
defaults read-type com.apple.finder AppleShowAllFiles

Erwartet (hängt von deinem Mac ab):

true
2026-10-10 08:40:11.463 defaults[93305:4051029]
The domain/default pair of (com.apple.dock, autohide) does not exist
Type is string

Schreiben übst du in einer eigenen Domain. Danach wird sie restlos gelöscht.

defaults write com.example.termlab KeyRepeat -int 2
defaults write com.example.termlab autohide -bool true
defaults read com.example.termlab
defaults delete com.example.termlab
defaults read com.example.termlab 2>&1 | tail -1

Erwartet:

{
    KeyRepeat = 2;
    autohide = 1;
}
Domain com.example.termlab does not exist

Das Skript $BUCH/bootstrap/macos-defaults.sh sammelt die Einstellungen. Ohne APPLY=1 ist es ein Trockenlauf, LAB_DOMAIN lenkt alle Schreibzugriffe in die Übungsdomain.

$BUCH/bootstrap/macos-defaults.sh | head -3
APPLY=1 LAB_DOMAIN=com.example.termlab $BUCH/bootstrap/macos-defaults.sh | tail -2
defaults read com.example.termlab | wc -l
defaults delete com.example.termlab

Erwartet:

DRY: defaults write NSGlobalDomain KeyRepeat -int 2
DRY: defaults write NSGlobalDomain InitialKeyRepeat -int 15
DRY: defaults write NSGlobalDomain ApplePressAndHoldEnabled -bool false
✔ com.example.termlab location = /Users/<du>/Screenshots
✔ com.example.termlab disable-shadow = true
      12

Der Kern ist eine Funktion set_default domain key typ wert – eine einzige Stelle für Trockenlauf und Umleitung. Schau sie dir mit bat $BUCH/bootstrap/macos-defaults.sh an.

Tipp: Welcher Schlüssel steckt hinter einem Häkchen in den Systemeinstellungen? defaults read > vorher.txt, Häkchen setzen, defaults read > nachher.txt, diff vorher.txt nachher.txt. Nur lesen, nichts schreiben.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Bootstrap-Skript – Trockenlauf

$BUCH/bootstrap/bootstrap.sh macht aus einem frischen Mac in sechs Schritten deinen Mac. Ohne --apply prüft es nur und zeigt, was es tun würde. Es ist idempotent: Ein zweiter Lauf überspringt Erledigtes.

shellcheck $BUCH/bootstrap/*.sh && echo "✔ shellcheck"
$BUCH/bootstrap/bootstrap.sh 2>&1 | grep -E '^(==>|✔|DRY|…)'

Erwartet (gekürzt, hängt von deinem Mac ab):

✔ shellcheck
==> 1/6 Xcode Command Line Tools
✔ vorhanden
==> 2/6 Homebrew
✔ Homebrew 7.0.9
==> 3/6 chezmoi + Dotfiles
✔ Quellverzeichnis existiert schon -> nur update
DRY: chezmoi update
==> 4/6 Pakete aus dem Brewfile
… Brewfile oder brew fehlt: /Users/<du>/.local/share/chezmoi/Brewfile
==> 5/6 macOS-Einstellungen
DRY: defaults write NSGlobalDomain KeyRepeat -int 2
…
==> 6/6 SSH-Key
✔ Key vorhanden
==> Fertig. Nächste Schritte: Checkliste in Tag 13.

Das Gerüst – set -euo pipefail, trap … ERR, run() für den Trockenlauf – vertieft Tag 14.

Auf dem neuen Mac reicht danach eine Zeile – vorausgesetzt, das Dotfiles-Repo ist erreichbar:

DOTFILES_REPO=https://github.com/DEIN-USER/dotfiles.git ./bootstrap.sh --apply

Warum HTTPS? Auf dem frischen Mac gibt es noch keinen SSH-Key bei GitHub – den erzeugt erst Schritt 6. Ein privates Repo klonst du per gh auth login oder Token. chezmoi init --apply <repo> klont das Repo nach ~/.local/share/chezmoi, fragt hosttype und E-Mail ab, schreibt alle Dateien und startet das run_onchange-Skript mit brew bundle.

Fortschritt speichern? Kostenlos registrieren

Drill 9: Ernstfall – die echte Konfiguration übernehmen

Bis hier lief alles im Lab. Wenn du bereit bist, übernimmst du deine Lab-Konfiguration bewusst ins echte Home. Lies die Schritte zuerst nur durch – sie ändern dein System.

# 1. Backup der echten Dateien (fehlende Dateien meldet tar, das ist ok)
cd ~ && tar czf ~/dotfiles-backup-$(date +%F).tgz \
  .zshrc .zshenv .zprofile .gitconfig .tmux.conf .config/nvim .config/starship.toml
# 2. Lab-Stand ins echte Home kopieren (Lab-Ordner config/zsh -> ~/.config/zsh)
mkdir -p ~/.config/zsh && cp ~/term-lab/config/zsh/*.zsh ~/.config/zsh/
# 3. Echtes chezmoi anlegen und Dateien aufnehmen (add ändert das Ziel nicht)
chezmoi init
chezmoi add ~/.zshrc ~/.gitconfig ~/.tmux.conf ~/.config/zsh ~/.config/nvim
chezmoi diff            # muss leer sein
# 4. Remote anlegen und pushen
chezmoi cd && gh repo create dotfiles --private --source=. --push

Achtung: Prüfe vor dem Push mit chezmoi git -- grep -nIE 'token|password|secret', dass kein Secret im Klartext in der Quelle liegt. Was du findest, wandert in ein Template mit onepasswordRead oder keyring.

Fortschritt speichern? Kostenlos registrieren

Checkliste: Neuer Mac in einer Stunde

Minute Schritt Befehl / Ort
0–10 Apple-ID, FileVault, Updates Systemeinstellungen
10–15 Xcode Command Line Tools xcode-select --install
15–20 Bootstrap holen und prüfen curl -fsSLO …/bootstrap.sh + lesen
20–45 Homebrew, chezmoi, Pakete ./bootstrap.sh --apply
45–50 Anmelden: 1Password, gh auth login danach chezmoi apply
50–55 SSH-Key bei GitHub/GitLab hinterlegen gh ssh-key add ~/.ssh/id_ed25519.pub
55–60 Abmelden/Anmelden, Startzeit messen hyperfine 'zsh -i -c exit'

Kontrollpunkt

#!/usr/bin/env zsh
source ~/term-lab/config/zsh/cz-lab.zsh
ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
H=$LAB/cz/home
cz managed | grep -qx .gitconfig \
  && ok "gitconfig verwaltet" || nok "gitconfig verwaltet"
cz data --format=json | jq -e '.hosttype' >/dev/null \
  && ok "hosttype gesetzt" || nok "hosttype gesetzt"
[[ $(stat -f %Lp $H/.config/termlab/secrets.env) == 600 ]] \
  && ok "secrets.env ist 0600" || nok "secrets.env ist 0600"
cz status | grep -q '^.M' && nok "Drift zwischen Quelle und Ziel" || ok "keine Drift"
cz git -- log --oneline | grep -q . \
  && ok "Quelle versioniert" || nok "Quelle versioniert"
defaults read com.example.termlab >/dev/null 2>&1 \
  && nok "Übungsdomain noch da" || ok "Übungsdomain gelöscht"
shellcheck $BUCH/bootstrap/*.sh && ok "Skripte shellcheck-sauber" || nok "shellcheck"

Erwartet:

✔ gitconfig verwaltet
✔ hosttype gesetzt
✔ secrets.env ist 0600
✔ keine Drift
✔ Quelle versioniert
✔ Übungsdomain gelöscht
✔ Skripte shellcheck-sauber

Challenge

Mach .zshrc zum Template: Nur auf einem work-Rechner lädt sie zusätzlich ~/.config/kunde/kunde.zsh mit dem Kunden-Proxy. Prüfe beide Rechnerarten mit cz cat.

Hinweis: cz chattr +template <ziel> hängt .tmpl an die Quelldatei an.

Lösung

H=$LAB/cz/home S=$LAB/cz/src
cz chattr +template $H/.zshrc
cat >> "$(cz source-path $H/.zshrc)" <<'EOF2'
{{- if eq .hosttype "work" }}
source ~/.config/kunde/kunde.zsh
{{- end }}
EOF2
echo 'export HTTPS_PROXY=http://proxy.kunde.example:3128' \
  > $S/dot_config/kunde/kunde.zsh
cz init --prompt --promptChoice Rechnerart=work \
  --promptString [email protected]
cz cat $H/.zshrc | tail -1
cz init --prompt --promptChoice Rechnerart=privat \
  --promptString [email protected]
cz cat $H/.zshrc | tail -1

Erwartet:

source ~/.config/kunde/kunde.zsh
export PAGER=less

Warum bleibt ~/.config/kunde nach einem früheren apply auf dem privaten Rechner liegen? Ignorieren heißt nur „nicht verwalten”. Zum Löschen trägst du den Pfad in .chezmoiremove ein.

Aufräumen nach dem Tag: rm -rf ~/term-lab/cz und defaults delete com.example.termlab 2>/dev/null.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Firmenrechner sind oft per MDM (Jamf, Intune) verwaltet: Profile überschreiben defaults, Homebrew braucht ggf. einen freigegebenen Pfad oder Proxy. Vorher mit der IT klären.
  • Dotfiles-Repo privat halten, trotzdem so pflegen, als wäre es öffentlich: Secrets nur über onepasswordRead, keyring oder age-Verschlüsselung (chezmoi add --encrypt).
  • Kundenspezifisches (Proxy, CA-Zertifikate, interne Registries) über hosttype oder eigene Daten wie .kunde trennen. Beim Projektende ausrollen mit .chezmoiremove.
  • Brewfile im Team teilen: ein gemeinsames Basis-Brewfile im Plattform-Repo, persönliche Ergänzungen im eigenen Dotfiles-Repo.
  • Bootstrap regelmäßig in einer frischen VM testen. CI kann shellcheck und chezmoi execute-template auf jedem Commit laufen lassen.