# Path mapping — the one setting you must get right

Media Purge deletes files through **its own** filesystem, but your media server reports paths
in **its** container's namespace. On unraid these rarely match.

## Example

| Where | How the share is mounted |
| --- | --- |
| unraid host | `/mnt/user/media` |
| Plex container | `/mnt/user/media` → `/data` |
| Media Purge container | `/mnt/user/media` → `/media` |

Plex reports `Movie.mkv` as `/data/movies/Movie.mkv`. Media Purge must translate that to
`/media/movies/Movie.mkv` before it can move the file.

**Settings → Path mappings → add:** `from: /data` → `to: /media`. Longest matching prefix wins,
so you can have both `/data` → `/media` and `/data/kids` → `/kids-media`.

If both containers mount the share at the identical path, leave mappings empty.

## Safety check

On approval, Media Purge verifies the item's files are actually reachable before touching
anything. If none are found you get an error pointing here instead of a bogus "deleted" — a
wrong mapping can never silently delete the wrong file, but a *technically valid* mapping that
points at the wrong tree could. Test with dry-run mode on (the default) and read the activity
log's `[DRY RUN]` entries to confirm the resolved paths look right before going live.

## Recycle bin placement

Put the recycle bin **on the same share/pool as your media** (e.g.
`/mnt/user/media/.media-purge-bin`). This is necessary for fast moves, but on a multi-disk
unraid array it is not always *sufficient* — read on before assuming a slow move means you've
misconfigured something.

### Why you'll still see "falling back to a full copy" sometimes

`/mnt/user` is a virtual union (shfs/FUSE) across your individual array disks. Two paths can
both live under the same **user share** — same folder, same mount, same everything you can see
— while the actual files underneath sit on different physical disks. unraid spreads a share's
files across disks per its allocation method (Fill-up, High-water, Most-free…), so a movie you
approve for deletion might physically be on `disk2` while the recycle-bin folder Media Purge
just created for it lands on `disk1`. The OS-level `rename()` call can't move a file across
physical disks atomically — it returns `EXDEV`, and Media Purge falls back to copy-then-delete,
which is what the log's "falling back to a full copy" line means. It's expected behavior for
multi-disk arrays, not a bug or a misconfiguration, and it's always safe — just slower for large
files.

**What actually fixes it:** nothing you can configure per-mapping — this is a property of your
array's disk layout, not of the mount paths. The only way to *guarantee* every move is an
instant rename is to keep your media on a single disk or a pool (e.g. a cache pool) rather than
a share spanning multiple array disks. That's a real storage-layout decision with its own
tradeoffs (redundancy, parity protection, expandability) — worth making deliberately, not as a
side effect of this app.

**If you just want to see whether it's happening on your setup:**

```bash
find /mnt/disk*/data/media -iname "*your movie title*" 2>/dev/null
find /mnt/disk*/data/media -iname ".media-purge-bin" -maxdepth 3 2>/dev/null
```

Different `diskN` in the two results confirms it. Media Purge logs one warning per approval
(not per file) when this happens, so a 57-episode season copying slowly is expected to show a
single warning line, not fifty-seven.