darktable-sync/CLAUDE.md

darktable-sync — Projektdokumentation für Claude

Zweck

Bash-Skripte zur bidirektionalen Synchronisation der Darktable-Datenbank und Fotobibliothek zwischen lokalem Rechner und einem Server via rsync/SSH. Entwickelt für Linux mit systemd.

Architektur

darktable_wrapper.sh   → Startet Pre-/Post-Sync, dann Darktable
darktable_sync.sh      → Hauptsync-Engine (Upload + Download)
darktable_common.sh    → Gemeinsame Hilfsfunktionen (wird per source eingebunden)

Ablauf darktable_sync.sh

1. Dependencies prüfen (rsync, ssh, notify-send, darktable)
2. Config laden und validieren
3. Lock erwerben (atomares mkdir)
4. Dry-Run-Modus prüfen (Standard: Trockenlauf; --execute/-e für echten Sync)
5. Darktable-Prozess prüfen (Sync verboten wenn darktable läuft)
6. Server-Erreichbarkeit prüfen → sync_pending bei Fehler
7. Active-Marker prüfen (verhindert gleichzeitige Clients)
8. Darktable-Versionen abgleichen (Major.Minor müssen übereinstimmen)
9. Sync-Token prüfen (Konflikterkennung bei mehreren Clients)
10. DB-Backup erstellen (library.db.bak, data.db.bak) — nur bei --execute
11. Backup-Verzeichnisse anlegen (${LOCAL_PHOTO_DIR}-bak, ${LOCAL_DARKTABLE_DB_DIR}-bak)
12. Upload: DB und Fotos mit --delete (lokal gelöscht → Server gelöscht)
13. Download: DB und Fotos mit --delete --backup --backup-dir (lokal gelöscht → ins -bak-Verzeichnis)
14. Sync-Token und Versionsdatei speichern
15. Alte Backups bereinigen (cleanup_old_backups, >730 Tage)

Konfiguration

• Datei: ~/.config/darktable-sync/.env (Permissions: 600)
• Wichtige Variablen: SERVER_IP, SERVER_USER, SERVER_SSH_PORT, SERVER_DB_DIR, SERVER_PHOTO_DIR, LOCAL_DARKTABLE_DB_DIR, LOCAL_PHOTO_DIR, DARKTABLE_BIN, SYNC_BIN
• Vorlage: .env.example

rsync-Flags

Operation	Flags
Upload DB	-uavh --itemize-changes --delete --exclude '*.lock' --exclude 'darktable_version'
Upload Fotos	-uavh --itemize-changes --delete --exclude '*.lock'
Download DB	-uavh --itemize-changes --delete --backup --backup-dir="${LOCAL_DARKTABLE_DB_DIR}-bak"
Download Fotos	-uavh --itemize-changes --delete --backup --backup-dir="${LOCAL_PHOTO_DIR}-bak"

Dry-Run: RSYNC_DRY_FLAG=(--dry-run) wird zu allen Aufrufen hinzugefügt.

itemize-changes Format

• >f+++++++++ — neue Datei (Upload)
• <f+++++++++ — neue Datei (Download)
• >f / <f ohne + — aktualisiert
• *deleting — gelöscht

Sicherheitsmechanismen

• validate_path: Blockiert ' " ; | & \ $ ( ) ` und .. in Pfaden (Server- UND lokale Pfade)
• load_config: Blockiert `; | & `` in der .env vor dem source
• Leeres Quellverzeichnis vor Upload → Abbruch (Schutz vor falschem Mount)
• Atomares Locking via mkdir
• SSH immer mit BatchMode=yes und ConnectTimeout=5

Test-Infrastruktur

• Framework: BATS (tests/*.bats)
• Stubs in tests/stubs/: rsync, ssh, darktable, notify-send, pgrep, zenity, kdialog
• Stub-Aktivierung: run_with_stubs setzt tests/stubs/ vorne in PATH
• Steuerung via Env-Variablen: RSYNC_STUB_FAIL, RSYNC_STUB_DRY_LINES, RSYNC_STUB_ARGS_FILE, SSH_STUB_FAIL, SSH_STUB_OUTPUT, PGREP_STUB_FOUND
• Setup: create_valid_env in tests/helpers/setup.bash; jeder Test bekommt isoliertes $HOME in $BATS_TMPDIR
• Tests ausführen: bats tests/

Installation

install.sh — interaktiv, prüft Dependencies, kopiert Skripte nach ~/.local/bin/, richtet systemd-Service ein.

Bekannte offene Punkte

• M1 (Security, niedrig): validate_path sieht $VAR nicht, da bash beim source .env bereits expandiert. Angreifer braucht Schreibzugriff auf .env — begrenzter Schaden.