mac-home/README-SYNC.md

mac-home Synchronisierungs-Toolset

Drei hilfreiche Werkzeuge um deine Dotfiles (~/.zshrc, ~/.gitconfig, etc.) zwischen deinem Home-Directory und diesem Repository zu synchronisieren.

📦 Dateien

Datei	Größe	Zweck
sync-home-content.sh	17 KB	Hauptscript mit 6 Synchronisierungs-Modi
SYNC-STRATEGY.md	10 KB	Ausführliche Dokumentation & Best Practices
QUICK-START.sh	6 KB	Quick-Start Guide (diesen hier lesen!)

---

🚀 Schnellstart

cd ~/mac-home

# 1. Status anschauen
./sync-home-content.sh status

# 2. Mit --dry-run testen (KEINE Änderungen)
./sync-home-content.sh sync --dry-run

# 3. Echte Synchronisierung
./sync-home-content.sh sync

---

🎯 Die 6 Modi

1. STATUS — Nur Information

Zeigt welche Dateien geändert wurden (ohne zu ändern).

./sync-home-content.sh status

2. PUSH — Repo → Home

Kopiert vom Repository ins lokale Home-Directory.
Nutze wenn: Git-Update vorhanden.

./sync-home-content.sh push

3. PULL — Home → Repo

Kopiert vom Home-Directory ins Repository.
Nutze wenn: Lokal Dateien bearbeitet.

./sync-home-content.sh pull

4. SYNC — Bidirektional

Intelligente 2-Wege Synchronisierung.
Nutze wenn: Du unsicher bist, was verändert wurde.

./sync-home-content.sh sync

5. CLEANUP — Alte Backups löschen

Entfernt Backups älter als 30 Tage.

./sync-home-content.sh cleanup

6. LIST — Verwaltete Dateien

Zeigt alle Dateien, die versioniert sind.

./sync-home-content.sh list

---

🛡️ Sicherheitsfeatures

✅ Backups: Vor jeder Änderung wird ein Backup erstellt (.sync-backups/)
✅ Dry-Run: Mit --dry-run testen ohne zu ändern
✅ Checksummen: Content-basierter Vergleich (md5sum, nicht Timestamp)
✅ Logs: Alles protokolliert in .sync-home-content.log
✅ Smart Conflict-Handling: Neuere Version gewinnt automatisch (oder interaktiv)

---

💡 Typische Workflows

Scenario 1: Lokal .zshrc bearbeitet

./sync-home-content.sh status        # "≠ geändert im Home: .zshrc"
./sync-home-content.sh pull --dry-run  # Test
./sync-home-content.sh pull           # Sync ins Repo
git -C home-content commit -am "Update .zshrc"
git -C home-content push

Scenario 2: Git-Pull → Home updaten

git pull                              # Repository updaten
./sync-home-content.sh push --dry-run  # Test
./sync-home-content.sh push           # Sync ins Home
source ~/.zshrc                       # (bei .zshrc reload)

Scenario 3: "Weiß nicht was los ist"

./sync-home-content.sh sync --dry-run -v  # Ausführlich sehen
./sync-home-content.sh sync               # Bi-direktional sync

---

📋 Optionen

Flag	Effekt	Beispiel
-d, --dry-run	Zeige nur, ohne zu ändern	./sync status --dry-run
-v, --verbose	Detaillierter Output	./sync status -v
-i, --interactive	Frage bei Konflikten	./sync sync --interactive
--no-backup	Keine Backups erstellen	./sync push --no-backup
-h, --help	Zeige Hilfe	./sync -h

---

📚 Dokumentation

• Quick-Start: ./QUICK-START.sh (ausgeben)
• Detaillierte Docs: Lies SYNC-STRATEGY.md
• Logs: cat .sync-home-content.log

---

🆘 Fehlerbehandlung

Backup versehentlich gelöscht?

# Schaue in .sync-backups nach
ls -lh .sync-backups/

# Restore
cp .sync-backups/.gitconfig.20260928_150000.backup home-content/.gitconfig

Falsche Synchronisierung?

# Checksum-Mismatch? Das sind die gültigen Einträge:
cd home-content && git ls-files

Script zu langsam?

• Normal für ~14 Dateien < 1 Sek (md5sum overhead minimal)
• Bei vielen Dateien: seq-Verarbeitung ist bewusst, nicht parallelisierbar

---

⚙️ Erweiterte Nutzung

Alias für schnellen Zugriff

# In ~/.zshrc hinzufügen:
alias synchome="~/mac-home/sync-home-content.sh"
alias synchome-status="~/mac-home/sync-home-content.sh status"
alias synchome-pull="~/mac-home/sync-home-content.sh pull --dry-run && ~/mac-home/sync-home-content.sh pull"

Cron-Job für regelmäßigen Sync

# Alle 2 Stunden
0 */2 * * * cd ~/mac-home && ./sync-home-content.sh sync >> /tmp/sync-home.log 2>&1

---

🔍 Strategie: Inhalt vs. Timestamp?

Das Script nutzt md5sum für Erkennung + Timestamp für Konflikt-Auflösung:

Aspekt	Methode	Grund
Änderung erkennen	md5sum (Content)	Zuverlässig, Zeitzone-unabhängig
Konflikt lösen	Timestamp (mtime)	Welche Version ist neuerer?
Nur in Repo?	git ls-files	Tracking nur versionierter Dateien

---

✅ Best Practices

IMMER TUN:

• ✓ Vor kritischen Änderungen status checken
• ✓ Mit --dry-run testen bevor echte Sync
• ✓ Logs regelmäßig prüfen: tail .sync-home-content.log
• ✓ Alte Backups mit cleanup entfernen (monatlich)

NICHT TUN:

• ✗ --no-backup ohne wichtigen Grund nutzen
• ✗ push als Standard-Modus (zu aggressiv)
• ✗ Mehrere Sync-Prozesse parallel laufen lassen
• ✗ .sync-backups/ von Hand löschen

---

📖 Weitere Ressourcen

• Detaillierte Erklärung der Modi: SYNC-STRATEGY.md (5 min Lesedauer)
• Troubleshooting: SYNC-STRATEGY.md → Abschnitt "Troubleshooting"
• Change-Management Strategie: SYNC-STRATEGY.md → Abschnitt "Change-Management"

---

🤖 Was das Script tut

1. Liest alle in git ls-files registrierten Dateien
2. Vergleicht deren Checksum zwischen Repo und Home
3. Erstellt automatisch Backups bei Änderungen
4. Synchronisiert basierend auf gewähltem Modus
5. Protokolliert alles in .sync-home-content.log
6. Entfernt alte Backups (> 30 Tage mit cleanup)

---

💬 Fragen?

Lesen Sie SYNC-STRATEGY.md - fast alle Fragen sind dort beantwortet!

---

Viel Erfolg beim Synchronisieren! 🎉