A desktop application for synchronizing darktable XMP files between two different darktable libraries. This enables a simpler setup than trying to keep the two databases in sync.
- XMP Diff Analysis: Compares darktable XMP files between archive and session directories
- Visual Comparison: Generates previews for all pairs of differing XMPs via
darktable-cli - Keyboard-Only Navigation: Designed for efficient keyboard-only workflow
- Batch Operations: Review files and decide which ones to keep, then execute all operations at once
- Edit in darktable: For difficult cases, allows you to open the two copies in darktable for fine inspection and editing
- Backup System: Automatic backups created before overwriting files (optional)
This application is in very early development and may have bugs or incomplete features. Use with caution on production workflows.
This app is an experiment in agent-assisted coding. The code has been almost completely generated by Gemini 2.5 Pro and Claude Sonnet 4, and it has not been inspected throughout.
- Archive Directory: Your reference/master library containing the baseline XMP files
- Session Directory: Your working library where you make current edits
The workflow assumes that the Session directory is a copy of (a subset of) the Archive directory. The two versions eventually diverge, and you want to reconcile them.
XMP (Extensible Metadata Platform) files store darktable's edit history and metadata for each image. The tool compares these files to identify differences in editing history.
- Archive: Desktop with full library
- Session: Laptop with subset for travel
- Sync: Merge laptop edits back to desktop
- Archive: Master library with finished edits
- Session: Working copy for experimentation
- Sync: Promote successful experiments to archive
- Archive: Shared reference library
- Session: Individual working copies
- Sync: Merge approved changes to shared library
- Archive: Backup of previous edit state
- Session: Current working library
- Sync: Selectively restore previous edits
This program only works on directories that contain:
- Two intersecting sets of XMPs and the accompanying RAW files
- Organized in a matching hierarchy
This program is not meant to:
- Merge two directories containing disjoint sets of files, or
- Merge two directories where the same files are organized according to different directory structures
- Darktable (and
darktable-cli) are installed on your system - Python 3.9+
- PySide6 (Qt for Python)
- lxml (XML processing)
pip install PySide6 lxmlpython3 src/main.py-
Launch the application
- Run the executable or
python main.pyfrom the src directory
- Run the executable or
-
Configure directories
- Click "Archive directory" button to select your reference library
- Click "Session directory" button to select your working library
- The application will remember these selections for future use
-
Configure settings (optional)
- Go to File → Settings... (or Cmd+, on macOS)
- Set darktable CLI path if not auto-detected
- Adjust preview generation settings
- Configure keyboard shortcuts
- Enable/disable backup creation
-
Scan for differences
- Click the "Scan" button
- The application will compare XMP files between directories
- Results appear in the "XMPs with differences" section
-
Review differences
- Select files from the tree view
- View edit history differences in the table
- Compare visual previews side-by-side
-
Plan actions
- For each file, choose an action:
- Keep archive: Copy archive version to session
- Keep session: Copy session version to archive
- Keep both: Keep both versions (no synchronization)
- No action: Skip this file
- For each file, choose an action:
-
Execute changes
- Use "Dry run" checkbox to preview changes without applying them
- Click "Execute planned actions" to apply your decisions
- Backups are created automatically (if enabled)
The interface is divided into two main areas:
- Input selection: Directory choosers and scan button
- XMPs with differences: Tree view of files with differences
- Selected XMP: Details for the currently selected file
- Planned action: Action buttons for the selected file
- Archive preview: Shows how the image looks with archive XMP
- Session preview: Shows how the image looks with session XMP
- Toolbar: Zoom, orientation, and comparison controls
Files are organized in a hierarchical tree structure matching your directory layout:
- Folders: Expandable directory structure
- Files: Individual XMP files with differences
- Labels: Show planned actions in brackets (e.g.,
[Keep session])
Use the checkboxes at the bottom of the file list to filter:
- Decided: Files with planned actions
- Undecided: Files without planned actions
- Counter shows number of files in each category
Shows differences between archive and session versions:
- Step: darktable processing step number
- Module: darktable module name (e.g., exposure, color correction)
- +: Present in session but not archive
- -: Present in archive but not session
- P: Parameters differ between versions
- M: Module order differs between versions
- Copies the archive version of the XMP file to the session directory
- Use when you want to revert session changes to match the archive
- Original session file is backed up (if enabled)
- Copies the session version of the XMP file to the archive directory
- Use when you want to promote session changes to the archive
- Original archive file is backed up (if enabled)
- No files are copied
- Both versions remain unchanged
- Use when you want to maintain divergent edit histories
- Default state for all files
- No synchronization occurs
- Files remain in their current state
- Side-by-side: Archive and session previews displayed simultaneously
- Synchronized: Zoom and pan operations affect both previews
- Color coding: Green/Red label indicates the version that will be kept/overwritten
- Previews are generated using darktable-cli
- Generation happens in the background
- Cache system avoids regenerating identical previews
- Zoom: Mouse wheel or keyboard shortcuts
- Pan: Click and drag to move around zoomed images
- Orientation: Toggle between horizontal and vertical layout
- Compare in darktable: Launch darktable with both versions loaded
The application supports efficient keyboard-only workflow. All shortcuts are customizable in File → Settings → Keyboard Shortcuts.
- Up/Down: Navigate up/down through file list
- Left/Right: Navigate to previous/next undecided file
- 1: Keep archive version
- 2: Keep session version
- 3: Keep both versions
- ` (backtick): Reset to no action
- E/Q: Zoom in/out on previews
- W/A/S/D: Scroll preview images
- R: Toggle preview orientation
- darktable CLI path: Path to darktable-cli executable (auto-detected on most systems)
- Enable OpenCL: GPU acceleration for preview generation
- Max dimension: Maximum preview size (affects quality vs speed)
- Max threads: Concurrent preview generation jobs
- Adjust based on your system capabilities
- Customizable shortcuts: Assign keys to all actions
- Default shortcuts: Sensible defaults provided
- Conflict detection: Prevents duplicate assignments
- Enable backups: Toggle backup creation
- Backup location: Same directory as original files
- Backup naming: Uses
.dtsync.bakextension
- No previews: Check darktable-cli path in settings
- Slow scanning: Reduce thread count or preview size
- Memory issues: Clear preview cache or reduce preview dimensions
- Keyboard shortcuts not working: Check for conflicts in settings
- Backup issues: Verify write permissions in directories
- Large libraries: May take time to scan initially
- Preview generation: Is CPU/GPU intensive
- Memory usage: Scales with number of files
If you encounter issues:
- Check the error messages in the application
- Verify darktable-cli is working:
darktable-cli --version - Test with a small subset of files first
- Check file permissions in both directories
- Works with XMP sidecar files only
- Requires matching RAW file structure
- Directory structure should be consistent between archive and session
- Designed for darktable 4.0+
- XMP format differences between versions may cause issues
- Test with small batches first
- Always test with copies first
- Verify backup system works
- Keep external backups of important work
Copyright (C) 2025 Daniele Pighin
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.