document_sorter/README_V1_5.md

Quick Sorter v1.5 — automatic collision resolution

V1.5 removes the manual collision-cleanup step from v1.4.

Collision rule

When two confirmed files want the same target name, or the target already exists:

1. The sorter compares the complete file contents with SHA-256.
2. If they are byte-identical:
   • the already-existing / first planned copy is kept;
   • the redundant source is marked EXACT → remove duplicate;
   • it is deleted only when you explicitly click Apply confirmed.
3. If the bytes differ:
   • neither file is overwritten or deleted;
   • the incoming file is renamed automatically with a visible suffix such as _variant-2, _variant-3, etc.

Example:

2026-09-01_cafe-bach_abrechnung.pdf
2026-09-01_cafe-bach_abrechnung_variant-2.pdf

GUI

A new Collision column shows the resolution directly in the main table:

EXACT → remove duplicate
DIFF → 2026-09-01_..._variant-2.pdf

You no longer need to deselect collision rows before Apply.

Apply confirmed gives one summary before touching disk:

• normal moves/renames
• different-content collisions kept as variants
• exact SHA-256 duplicates that will be removed
• unchanged files

Important safety boundary

EXACT means byte-for-byte identical after a full-file SHA-256 comparison. A PDF/DOCX that looks the same but has different embedded metadata is treated as DIFF and kept as a variant. This is intentionally conservative.

Existing files are never overwritten. Every Apply is logged in .quick_sorter_log.csv.