# 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

```bash
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).
```bash
./sync-home-content.sh status
```

### 2. **PUSH** — Repo → Home
Kopiert vom Repository ins lokale Home-Directory.  
**Nutze wenn:** Git-Update vorhanden.
```bash
./sync-home-content.sh push
```

### 3. **PULL** — Home → Repo
Kopiert vom Home-Directory ins Repository.  
**Nutze wenn:** Lokal Dateien bearbeitet.
```bash
./sync-home-content.sh pull
```

### 4. **SYNC** — Bidirektional
Intelligente 2-Wege Synchronisierung.  
**Nutze wenn:** Du unsicher bist, was verändert wurde.
```bash
./sync-home-content.sh sync
```

### 5. **CLEANUP** — Alte Backups löschen
Entfernt Backups älter als 30 Tage.
```bash
./sync-home-content.sh cleanup
```

### 6. **LIST** — Verwaltete Dateien
Zeigt alle Dateien, die versioniert sind.
```bash
./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
```bash
./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
```bash
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"
```bash
./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? 
```bash
# Schaue in .sync-backups nach
ls -lh .sync-backups/

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

### Falsche Synchronisierung?
```bash
# 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
```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"
```

### Cron-Job für regelmäßigen Sync
```bash
# 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! 🎉**