Fix-Trash Command¶
The fix-trash
command ensures stack consistency by moving related assets to trash when their stack members have been deleted.
Overview¶
When you delete a photo in Immich that's part of a stack (e.g., one photo from a burst sequence), the other photos in that stack should typically be deleted too. However, if photos are deleted through the Immich UI or other means, related stack members might remain in your library.
This command:
- Scans your trash for deleted assets
- Identifies which active assets would stack with the trashed ones
- Moves those related assets to trash to maintain consistency
How It Works¶
The command uses the same stacking criteria as the main stacking command. For each trashed asset:
- It combines the trashed asset with all active assets
- Runs the stacking algorithm to find matches
- Any active assets that would group with the trashed asset are marked for deletion
Usage¶
immich-stack fix-trash [flags]
Examples¶
Basic Usage¶
immich-stack fix-trash --api-key your_key --api-url http://immich:2283
Dry Run Mode¶
See what would be deleted without making changes:
immich-stack fix-trash --api-key your_key --dry-run
With Custom Criteria¶
Use specific stacking criteria for matching:
immich-stack fix-trash --api-key your_key --criteria '[{"key":"originalFileName","regex":{"pattern":"BURST(\\d+)","index":1}}]'
Debug Mode¶
Get detailed information about the matching process:
immich-stack fix-trash --api-key your_key --log-level debug
Output¶
The command provides detailed feedback:
🗑️ Found 5 trashed assets
📊 Analyzing against 1000 active assets...
✅ Analysis complete: 5 trashed → 15 related assets to trash
📁 Assets to trash by type:
- JPG files: 10
- DNG files: 5
🗑️ Moving 15 assets to trash... done
In debug mode, you'll see detailed stack information:
📋 Summary of assets to trash:
Stack with DSC_0001_BURST.jpg (in trash): DSC_0002_BURST.jpg, DSC_0003_BURST.jpg
Stack with IMG_1234.jpg (in trash): IMG_1234.dng
Flags¶
The command uses all global flags, particularly:
--dry-run
- Preview what would be deleted without making changes--criteria
- Custom stacking criteria (uses same format as main command)--parent-filename-promote
- Filename patterns for stacking--log-level
- Set todebug
for detailed matching information
Use Cases¶
1. Post-Deletion Cleanup¶
After deleting photos through Immich UI:
# Clean up related assets after manual deletion
immich-stack fix-trash --api-key your_key
2. Burst Photo Management¶
When you delete one photo from a burst sequence:
# Ensure all burst photos are deleted together
immich-stack fix-trash --api-key your_key --parent-filename-promote "sequence"
3. RAW+JPEG Cleanup¶
After deleting JPEG files, remove orphaned RAW files:
# First check what would be deleted
immich-stack fix-trash --api-key your_key --dry-run
# Then execute if correct
immich-stack fix-trash --api-key your_key
4. Scheduled Maintenance¶
Add to a cron job for automatic cleanup:
# Run weekly to maintain consistency
0 2 * * 0 immich-stack fix-trash --api-key your_key --log-level warn
Important Notes¶
- Uses Stacking Criteria: The command uses the same criteria as the main stacking command
- Irreversible: Moving assets to trash cannot be undone through this tool
- Performance: For large libraries, analysis may take several minutes
- Safety First: Always use
--dry-run
first to preview changes
Best Practices¶
- Test with Dry Run: Always run with
--dry-run
first - Review Debug Output: Use
--log-level debug
to understand matching logic - Backup Important Data: Ensure you have backups before running
- Regular Maintenance: Run periodically to maintain library consistency
Common Scenarios¶
Incomplete Burst Deletion¶
# You deleted DSC_0001_BURST but DSC_0002_BURST remains
immich-stack fix-trash --api-key your_key
# Output: Will move DSC_0002_BURST to trash
Orphaned RAW Files¶
# You deleted IMG_1234.jpg but IMG_1234.dng remains
immich-stack fix-trash --api-key your_key
# Output: Will move IMG_1234.dng to trash
See Also¶
- Main Stacking Command - Create stacks from your assets
- Duplicates Command - Find duplicate assets
- Stacking Logic - Understand how assets are grouped
- Custom Criteria - Configure matching rules