# 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.