---
name: organize-photos
description: General photo/video organiser for any messy folder - old drives, phone dumps, "Camera Uploads", WhatsApp/Downloads piles, a parent's laptop. Sorts by the real capture date (EXIF, video metadata, dates in file names) into Year/Month (or Day/Trip) folders, parks screenshots, shared images, non-media, undated files and checksum-proven duplicates in honestly named holding folders, and is fully reversible (plan -> review -> apply -> undo). Never deletes. Cross-platform Python, no installs. Use for "organize my photos", "sort this folder of pictures by date", "clean up this photo dump".
---

# organize-photos

The general-purpose sibling of `sort-trip-photos` (one trip, day folders) and `photo-archive` (cloud libraries,
verified uploads, deleting at the source). Use this one when someone just wants a pile of pictures in order.

## Usage
```
python -I scripts/organize_media.py plan  <src> <dest> plan.csv [--layout=month|day|year] [--trips=trips.csv]
                                          [--screenshots=separate|inline] [--shared=separate|inline] [--mtime=allow|undated]
python -I scripts/organize_media.py apply plan.csv [--copy] [--dry-run]
python -I scripts/organize_media.py undo  <dest>/_organize_log/move_log_<stamp>.csv
python -I scripts/remove_empty_dirs.py <src> [--apply]       # afterwards, only if the user wants empty folders gone
```
`<dest>` may equal `<src>` (sort in place) or be an existing library (new files are merged in; files already there
byte-for-byte are flagged as duplicates instead of copied twice).

## Principles (shared with the /reorganize way of working)
1. **Survey before you sort.** Run `plan` first and read its summary: counts per folder, date sources, how many are
   dated only by file time (LOW confidence). A filename is a hint, not a fact.
2. **Follow the existing structure.** If `<dest>` already has a scheme (`2019/07 July`, `Photos/2019/...`, per-event
   folders), adapt: pick the matching `--layout`, or sort into it by hand from the plan. Don't impose a second scheme.
3. **Real dates, best source first**: EXIF > video metadata (UTC -> `--tz`) > PNG XMP > date in the name > file time.
   File times on copied drives are usually the copy date - prefer `--mtime=undated` when most files came off another
   disk, and say how many files that affects.
4. **Checksum before calling anything a duplicate.** Only size + MD5 equality counts. Duplicates go to
   `duplicates_safe_to_delete_later/` with the kept copy named in the plan. The user deletes, not you.
5. **Never delete, never overwrite, never re-encode.** Moves are logged and undoable; collisions get `_dup1`.
6. **Don't force ambiguous things.** Screenshots -> `Screenshots/<year>`, received/forwarded media ->
   `Shared/<year>`, no date -> `_undated`, non-media -> `_not_media`. Say what is in them.
7. **Look when it matters.** For doubtful groups (LOW confidence dates, `_undated`, a burst of shared images), build a
   contact sheet (`sort-trip-photos/scripts/contact_sheet.ps1` on Windows, or open a handful) before deciding.
8. **Big moves in one run, then verify**: `apply` once; then compare: files in plan = files at destinations, source
   left with nothing unexpected. Re-running `apply` after an interruption skips what already moved.
9. **Report briefly**: per-folder counts, date-source mix, what sits in each holding folder and why, duplicates and
   what they duplicate, anything left in the source, where the undo log is.

## Options worth knowing
- `--trips=trips.csv` (`Name,Start,End`) puts those days in `<YYYY>/Trips/<YYYY-MM_Name>/`.
- `--months-folder` gives `<YYYY>/Months/<MM_Mon>` (the photo-archive layout) - use it when merging into that archive.
- `--copy` leaves the source untouched (safest for someone else's disk); `undo` then leaves the copies in place.
- Sidecars (`.AAE`, `.XMP`, Takeout `.json`, `.THM`) travel with their photo; orphans go to `_not_media/orphan_sidecars`.

## Not for
Cloud libraries and freeing cloud storage (use `photo-archive`), a single trip into day folders with EXIF fixes
(use `sort-trip-photos`), documents and other non-media clutter (use `organize-folder`).