Implement sync script and setup documentation

SYNC-STRATEGY.md

@@ -0,0 +1,423 @@
+# 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
+```bash
+./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
+```bash
+./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
+```bash
+./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)
+```bash
+./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:**
+```bash
+# 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
+```bash
+./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
+```bash
+./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
+```bash
+.sync-backups/
+├── .gitconfig.20260928_150000.backup          # Timestamp = YYYYMMDD_HHMMSS
+├── .gitconfig.20260925_200000.backup
+└── .zshrc.20260927_120000.backup
+```
+
+### Restore aus Backup
+```bash
+# Beispiel: .gitconfig wiederherstellen
+cp .sync-backups/.gitconfig.20260928_150000.backup home-content/.gitconfig
+```
+
+---
+
+## Workflow-Beispiele
+
+### Scenario 1: Neue `.gitconfig` lokal
+```bash
+# 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
+```bash
+# 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
+```bash
+./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:**
+```bash
+./sync-home-content.sh sync --dry-run --verbose --interactive
+```
+
+---
+
+## Logs & Debugging
+
+### Log-Datei
+Alle Operationen werden protokolliert in `.sync-home-content.log`:
+```bash
+tail -f .sync-home-content.log
+```
+
+### Verbose Debug-Output
+```bash
+./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"
+```bash
+# Prüfe ob in Repository:
+pwd
+# Sollte: /Users/u241100/mac-home
+
+# Prüfe git Status:
+git status
+```
+
+### Problem: "Permission denied" auf Backup
+```bash
+# Prüfe .sync-backups Permissions:
+ls -ld .sync-backups
+chmod 755 .sync-backups
+chmod 644 .sync-backups/*
+```
+
+### Problem: Datei wurde falsch überschrieben
+```bash
+# 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
+```bash
+# 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)
+```bash
+# .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
+```bash
+# 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
+
+```bash
+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.
+
+