Why batch renaming eats files, and the two-phase fix

Rename a set of files one at a time and you will eventually destroy one. The failure is predictable and so is the fix.

Buck Kettering · September 2026

Every batch renamer looks fine on a folder of holiday photos. The failure only shows up when the new names and the old names overlap, and by then a file is already gone.

This is the failure, why it happens, and the fix. It applies to any tool you use, including a five line shell loop.

1. The chain

You have three episodes. The numbering was off by one, so every file needs to shift down:

Show - S01E02.mkv   ->   Show - S01E01.mkv
Show - S01E03.mkv   ->   Show - S01E02.mkv
Show - S01E04.mkv   ->   Show - S01E03.mkv

Rename them in order, one at a time. The first operation writes to Show - S01E01.mkv, which is fine. The second writes to Show - S01E02.mkv, which still exists, because it is the file waiting its turn.

On most systems the rename call replaces the destination without asking. The tool reports three successes. You have two files.

2. The swap

Worse, and more common than people expect, because two files got mismatched at import:

Episode A.mkv   ->   Episode B.mkv
Episode B.mkv   ->   Episode A.mkv

There is no ordering that works. Whichever you move first destroys the other. A tool that only checks each rename against the current state of the disk cannot solve this, so most of them refuse the whole batch and tell you to sort it out yourself.

3. The fix is two phases

Do not rename anything to its final name on the first pass. Move every file in the batch to a unique temporary name, then move each one from its temporary name to its destination.

Phase 1
  Show - S01E02.mkv  ->  .tmp-0001
  Show - S01E03.mkv  ->  .tmp-0002
  Show - S01E04.mkv  ->  .tmp-0003

Phase 2
  .tmp-0001  ->  Show - S01E01.mkv
  .tmp-0002  ->  Show - S01E02.mkv
  .tmp-0003  ->  Show - S01E03.mkv

After phase one, none of the destination names are occupied by anything in the batch, because every batch member is sitting under a temporary name. Chains resolve. Swaps resolve. Order stops mattering.

4. Validate against the final state, not the current one

The other half of the problem is the preview. Checking "does a file with this name already exist" tells you almost nothing, because it asks about the disk as it is now, not as it will be.

Three things have to be checked before anything moves.

Two files in the batch resolving to the same destination name. This is the one that silently eats a file, and it is common when two rips of the same movie differ only in resolution and your template does not include it.

A destination that collides with a file already in the folder and not part of the batch.

A destination that is currently another batch member's source name. That is the chain. It is safe under two-phase, but you still want it visible.

5. Case-insensitive filesystems will lie to you

APFS and NTFS are usually case-insensitive but case-preserving. Renaming report.pdf to Report.pdf is either a no-op, an error, or a real rename, depending on the volume.

You cannot infer this from the platform. A Mac can be running a case-sensitive APFS volume. An SMB share can report one thing and behave another way, and some NAS firmware is simply wrong about it.

The reliable answer is to stop asking and test. Write a probe file with a mixed-case name, stat the lowercase version, delete the probe. One write and one stat per volume, cached for the session. It takes milliseconds and removes an entire class of bug.

6. Decide what happens when file 22 fails

Batches fail partway. A file is locked, a share drops, permissions differ on one subfolder. There are only three honest responses.

Stop and report. Name the file, the reason, and what has already been done.

Stop and roll back. Undo the completed operations and leave the folder as it was found.

Continue, then report with a list of what did not happen.

The wrong answer, and the common one, is to skip the failure silently and keep going. The batch reports success, the count is short, and nobody notices until a file cannot be found weeks later.

7. Undo has to be one unit

If a batch is one decision for the user, it should be one entry in the undo history. Undoing a hundred renames one hundred times is not an undo feature.

That means recording the mapping, not just the new names. Store source and destination for every operation and reverse them in the opposite order. Under two-phase renaming the reverse is another two-phase pass, for exactly the same reason the forward direction was.

What it costs

Two phases means twice as many rename calls. On a local disk that is imperceptible, because a rename is a metadata operation and never touches the file contents. Over SMB it is two round trips instead of one, which is still far cheaper than restoring one file from backup.

The preview is where the real work happens, and it is worth doing every time. A rename you can read before it runs is the whole difference between a tool you trust with four thousand files and one you use on ten at a time.

Related: what breaks when you rename over SMB and NAS shares and how to name TV and movie files so Plex and Jellyfin actually match them.