mac-home/SYNC-STRATEGY.md

Synchronisierungs-Strategie für home-content

Überblick

Das Script sync-home-content.sh synchronisiert Dateien zwischen dem Git-Repository (home-content/) und dem echten Home-Verzeichnis ($HOME).

Schlüsselprinzipien:

• ✓ Nur Dateien sync, die in git ls-files versioniert sind
• ✓ Content-basierte Erkennung via md5sum (verlässlicher als Timestamps)
• ✓ Automatische Backups bei Änderungen (.sync-backups/)
• ✓ Mehrere Modi für verschiedene Szenarien
• ✓ Sicher via Dry-Run vor echten Änderungen

---

Modi & Anwendungsfälle

1. STATUS (Standard) — Nur Information

./sync-home-content.sh status
./sync-home-content.sh status -v  # verbose mit Checksummen

Was es tut:

• Vergleicht alle Dateien im Repo mit Home-Dir
• Zeigt Unterschiede via md5sum
• Ändert nichts

Ausgabe-Bedeutungen:

Symbol	Bedeutung
✓	Datei ist identisch
≠	Datei geändert im Home-Dir
✚	Datei nur im Repo (nicht im Home)

Use-Case: Am Anfang, um zu sehen, was sich geändert hat

---

2. PUSH — Repo → Home-Dir

./sync-home-content.sh push --dry-run  # Erst testen
./sync-home-content.sh push            # Echte Synchronisierung

Was es tut:

• Kopiert Dateien vom Repo ins Home-Dir
• Überschreibt lokale Änderungen ohne zu fragen
• Erstellt Backup von geänderten lokalen Dateien (.sync-backups/)
• Neue Dateien: einfach kopieren ohne Backup

Ablauf:

1. Status 0 (identisch):     unverändert
2. Status 3 (geändert):      Backup Home → Repo → Home (Repo gewinnt)
3. Status 4 (nur Repo):      Kopieren ohne Backup

Use-Case:

• Repo-Dateien sind authoritative Version (z.B. nach Git-Pull)
• Lokale Änderungen waren Fehlgriffe
• Schnelle Synchronisierung nach .gitconfig Update

---

3. PULL — Home-Dir → Repo

./sync-home-content.sh pull --dry-run  # Erst testen
./sync-home-content.sh pull            # Echte Synchronisierung

Was es tut:

• Kopiert veränderte Dateien vom Home-Dir ins Repo
• Nur Updates bei geänderten Dateien
• Erstellt Backup der Repo-Dateien vor Update
• Nur im Home existierende Dateien: ignoriert

Ablauf:

1. Status 0 (identisch):     unverändert
2. Status 3 (geändert):      Backup Repo → Home → Repo (Home gewinnt)
3. Status 4 (nur Repo):      ignoriert (nicht im Home)

Use-Case:

• Lokale Änderungen sind wichtig (z.B. neue .gitconfig)
• Diese sollen ins Repo → für andere Maschinen verfügbar machen
• Git-Commit erforderlich nach Pull

---

4. SYNC — Bidirektional (Klug)

./sync-home-content.sh sync --dry-run          # Testen
./sync-home-content.sh sync                    # Auto-Konflikt-Lösung
./sync-home-content.sh sync --interactive      # Fragen bei Konflikten

Was es tut:

• Bidirektionale Synchronisierung
• Automatisch: Neuere Datei gewinnt (via Timestamp)
• Interaktiv: Benutzer wählt bei jedem Konflikt

Konflikt-Handling (Non-Interactive):

Wenn beide unterschiedlich:
- Home neuerer (mtime) → Home gewinnt (→ Repo)
- Repo neuerer (mtime) → Repo gewinnt (→ Home)

Konflikt-Handling (Interactive):

Optionen für jede konflikt-Datei:
1) Nehme Repo-Version (→ Home überschreiben)
2) Nehme Home-Version (← Repo überschreiben)
3) Behalte beide (Home als Backup aufbewahren)
4) Überspringe diese Datei

Beispiel Workflow:

# 1. Anschauen, was zu sync ist
./sync-home-content.sh status -v

# 2. Sicher testen
./sync-home-content.sh sync --dry-run

# 3. Interaktiv bei Konflikten
./sync-home-content.sh sync --interactive

# 4. Backups prüfen
ls -lh .sync-backups/

Use-Case:

• Routine-Sync mit potentiellen lokalen Änderungen
• Sicherheit durch Backups
• Smart: neuere Versionen gewinnen automatisch

---

5. CLEANUP — Alte Backups löschen

./sync-home-content.sh cleanup

Was es tut:

• Löscht Backups älter als 30 Tage
• Spart Speicherplatz

Backup-Struktur:

.sync-backups/
├── .gitconfig.20260928_150000.backup
├── .gitconfig.20260925_140000.backup    ← älter als 30 Tage → löschen
├── .zshrc.20260927_180000.backup
└── ...

---

6. LIST — Zeige verwaltete Dateien

./sync-home-content.sh list

Gibt alle Dateien aus, die versioniert sind (git ls-files).

---

Change-Management Strategie

Inhalt vs. Timestamp?

Das Script nutzt Content-Vergleich (md5sum) als Primär-Verfahren:

Ansatz	Vorteile	Nachteile
Checksum (md5)	Erkennt wirkliche Änderungen, Zeitzone-unabhängig	Minimal langsamer
Timestamp	Schnell	Falsch-Positive bei cp/rsync, Zeitzone-sensibel

Strategie:

1. Erkennung: md5sum → schnelle, zuverlässige Erkennung echter Änderungen
2. Konflikt-Auflösung: Timestamp (mtime) → welche Version ist neuerer

---

Backup-Strategie

Automatische Backups

• Bei Push: Backup der lokalen (überschriebenen) Datei vor Update
• Bei Pull: Backup der Repo-Datei vor Update
• Bei Sync: Backup je nach Konflikt-Lösung
• Deaktivierbar: --no-backup Option

Backup-Verzeichnis

.sync-backups/
├── .gitconfig.20260928_150000.backup          # Timestamp = YYYYMMDD_HHMMSS
├── .gitconfig.20260925_200000.backup
└── .zshrc.20260927_120000.backup

Restore aus Backup

# Beispiel: .gitconfig wiederherstellen
cp .sync-backups/.gitconfig.20260928_150000.backup home-content/.gitconfig

---

Workflow-Beispiele

Scenario 1: Neue .gitconfig lokal

# 1. Bearbeite lokal im Home
vim ~/.gitconfig

# 2. Check Status
./sync-home-content.sh status
# Output: ≠ geändert im Home: .gitconfig

# 3. Ins Repo synchronisieren
./sync-home-content.sh pull --dry-run
# Output: ← update: .gitconfig (Home → Repo)

./sync-home-content.sh pull
# Output: Backup erstellt: .gitconfig (vor Pull) → .sync-backups/.gitconfig.20260928_XXX

# 4. Git-Commit
cd home-content
git diff .gitconfig
git add .gitconfig
git commit -m "chore: update .gitconfig"
git push

Scenario 2: Repo-Update von anderer Maschine

# 1. Remote fetch (Git Pull)
git pull origin main

# 2. Check Status
./sync-home-content.sh status
# Output: ≠ geändert im Home: .zshrc

# 3. Repo-Version ins Home
./sync-home-content.sh push --dry-run
# Output: → update: .zshrc (Repo → Home) [lokale Änderung wird überschrieben]

./sync-home-content.sh push
# Output: Backup erstellt: .zshrc (vor Push) → .sync-backups/.zshrc.20260928_XXX

# 4. Neue Datei aktiv (Shell reload bei .zshrc)
source ~/.zshrc

Scenario 3: Bidirektional mit Konflikten

./sync-home-content.sh sync --interactive
# Für jede Konflikt-Datei: interaktiv wählen

# Oder Auto-Modus (neuere gewinnt)
./sync-home-content.sh sync

---

Optionen Referenz

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

Kombinierbar:

./sync-home-content.sh sync --dry-run --verbose --interactive

---

Logs & Debugging

Log-Datei

Alle Operationen werden protokolliert in .sync-home-content.log:

tail -f .sync-home-content.log

Verbose Debug-Output

./sync-home-content.sh status -v

Output zeigt:

• Checksummen für jede Datei
• Genaue Änderungstypen
• Schritt-für-Schritt Durchsatz

---

Best Practices

✓ TUN:

1. Vor kritischen Änderungen: status checken
2. Vor echtem Sync: --dry-run testen
3. Periodisch Backups prüfen: ls -lh .sync-backups/
4. Nach Push: Git-Commit & Push (falls Repo-Änderungen)
5. Verbose nutzen: Bei Unsicherheiten -v Option

✗ NICHT:

1. --no-backup ohne Grund nutzen (Backups sind Rettungsanker)
2. push Mode als Standard (zu aggressiv)
3. Logs löschen ohne Archivierung
4. Alte Backups manuell löschen (dafür cleanup)
5. Mehrere Sync-Prozesse parallel laufen lassen

---

Troubleshooting

Problem: "git: command not found"

# Prüfe ob in Repository:
pwd
# Sollte: /Users/u241100/mac-home

# Prüfe git Status:
git status

Problem: "Permission denied" auf Backup

# Prüfe .sync-backups Permissions:
ls -ld .sync-backups
chmod 755 .sync-backups
chmod 644 .sync-backups/*

Problem: Datei wurde falsch überschrieben

# 1. Finde richtiges Backup
ls .sync-backups/ | grep dateiname

# 2. Restore
cp .sync-backups/dateiname.YYYYMMDD_HHMMSS.backup home-content/dateiname

# 3. Ggf. manual zurückschreiben nach Home
cp home-content/dateiname ~/dateiname

Problem: Script ist zu langsam

• Meist normal (für 14 Dateien < 1 Sek)
• Bei Verzeichniss-Inhalten mit vielen Dateien: md5sum ist minimal-overhead

---

Integration in Workflow

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"

Pre-Commit Hook (Optional)

# .git/hooks/pre-commit
#!/bin/bash
~/mac-home/sync-home-content.sh status
# Bricht ab, wenn Unterschiede existieren

Cron-Job für regelmäßigen Sync

# Jeden Tag um 2 Uhr nachts
0 2 * * * cd ~/mac-home && ./sync-home-content.sh sync >> /tmp/sync-home.log 2>&1

---

Zusammenfassung Konflikt-Handling

Szenario	Pull	Push	Sync (Auto)	Sync (Interactive)
Datei identisch	—	—	—	—
Nur Home geändert	Home gewinnt	—	neuere (Home) gewinnt	Benutzer wählt
Nur Repo geändert	—	Repo gewinnt	neuere (Repo) gewinnt	Benutzer wählt
Beide geändert	—	—	neuere (Timestamp) gewinnt	Benutzer wählt (4 Optionen)
Nur im Repo	ignoriert	kopiert	kopiert	kopiert

---

Checkliste für neuen Rechner

cd ~/mac-home

# 1. Status prüfen
./sync-home-content.sh status

# 2. Neue Dateien trocken kopieren
./sync-home-content.sh push --dry-run

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

# 4. Backups überprüfen (sollten leer sein)
ls -la .sync-backups/

# 5. Log prüfen
tail .sync-home-content.log

Fertig! Home-Verzeichnis ist jetzt mit Repository sync.