Renaming Files Without Losing One

By the end of this lesson you can take the survey from the previous lesson, compute the new name for every file before touching any of them, detect the case where two files want the same new name, and refuse the entire operation rather than performing the half of it that happens to be safe.

Renaming is the most dangerous thing in this module, and it does not look dangerous.

Here is the whole problem in two files. A folder contains Invoice 2026-01.pdf and Invoice-2026-01.pdf — a scan and a re-scan, saved under different names. These names coexist on Windows as well as POSIX filesystems. A tidying script lowercases names and replaces spaces with hyphens. Both files want to become invoice-2026-01.pdf.

If a script iterates those sources and applies both moves with os.replace without a preflight collision check, both calls can succeed while the folder ends with one file. Which file survives under the new name depends on iteration order. A summary saying two moves completed could be true while silently hiding the overwritten file.

That is not a rare edge case. Spaces versus hyphens and copies named report (1).csv are common; case-only pairs also occur on case-sensitive filesystems. Any normalising rule maps some distinct names together.

The fix is not a cleverer naming rule. It is to compute every target first, look at the whole set, and treat "two sources, one target" as a reason to stop — because at that point a person has to decide which file is the real one, and that is exactly the handoff the first module taught you to find.

Plan every target before moving anything. The survey produces a list of (source, target) pairs. That list is data, it can be printed and reviewed, and — the point of this lesson — it can be checked as a whole before any of it happens.

The collision check is one line over the finished plan. Count how many sources produce each target; any target with more than one source is a collision. Doing this per file as you go cannot work: the second file only conflicts with the first once the first has been decided, and by then it has often already moved.

There are three target situations worth distinguishing:

1. Two sources, one target. Two files in the plan normalise to the same name.
2. A target that already exists outside the plan. A selected subset may aim at an excluded file, or a file may aim at an existing directory. This example plans every ordinary file, so it does not exercise the excluded-file case.
3. A target that is already a source in the plan. With this idempotent naming rule, a file already named correctly maps to itself; that is a no-op, not a collision. A different rule could make one source want another source's old name, which needs a deliberate ordering or temporary-name plan.

How to move a file, and what each one does when the target exists:

path.rename(target)      Windows: raises FileExistsError. Linux/macOS: replaces silently.
os.replace(src, target)  Requests replacement on every platform; one move is not a batch transaction.
shutil.move(src, target) An existing file may be overwritten; moves *into* a target directory.

path.rename behaving differently on different platforms is a real trap: code tested on Windows raises where code tested on Linux quietly overwrote. os.replace consistently requests replacement of an existing target; one successful rename is atomic where the platform guarantees it, but a loop of renames is not a transaction. It overwrites. Neither call checks the whole plan for you; the planning check is yours.

shutil.move also moves a source inside an existing destination directory. For an existing file, whether it is overwritten depends on os.rename behavior and fallback; do not use it as a no-overwrite guarantee.

Refuse the whole plan, not the offending file. A plan with one collision in it describes a folder somebody is confused about. Applying the other nineteen renames leaves that folder in a state that is neither what it was nor what was intended, and the person who has to sort it out now has to work out which nineteen already happened. Stopping costs one run; a half-applied plan costs an afternoon.

A plan, a collision check, and an apply step that respects it:

import os
import pathlib
import tempfile

root = pathlib.Path(tempfile.mkdtemp()) / "scans"
root.mkdir(parents=True)
for name in ["Receipt March.PDF", "receipt-March.PDF", "Ledger 2026.csv"]:
    (root / name).write_text(name, encoding="utf-8")


def filed_name(path):
    """Lowercase, spaces to hyphens, suffix lowercased."""
    return path.stem.lower().replace(" ", "-") + path.suffix.lower()


def plan_renames(folder):
    moves = sorted((entry.name, filed_name(entry)) for entry in folder.iterdir() if entry.is_file())
    targets = {}
    for source, target in moves:
        targets.setdefault(target, []).append(source)
    collisions = sorted(target for target, sources in targets.items() if len(sources) > 1)
    return moves, collisions


moves, collisions = plan_renames(root)
for source, target in moves:
    print(f"would rename {source} -> {target}")
print("collisions:", len(collisions))
for target in collisions:
    print("  contested target:", target)
print("applied:", 0)  # this is a dry run; no rename call occurs
print("still present:", len(sorted(root.iterdir())))

setdefault(target, []).append(source) builds "which sources want this target" in one pass. Keeping the sources, rather than just counting, is what lets the message name the two files a person has to choose between.

The applied: 0 line reports what this dry run actually does: it never calls a rename, whether or not the plan has a collision. The exercise adds the real move and refuses its detected collision before that move loop.

still present reads the folder again at the end. Its count supports the dry-run claim in this isolated sample, but equal counts alone would not prove that names or bytes stayed unchanged. Compare a before/after inventory when checking real files.

Predict every line.

would rename Ledger 2026.csv -> ledger-2026.csv
would rename Receipt March.PDF -> receipt-march.pdf
would rename receipt-March.PDF -> receipt-march.pdf
collisions: 1
  contested target: receipt-march.pdf
applied: 0
still present: 3

Delete the collision check entirely and make the loop rename as it goes:

for entry in root.iterdir():
    if entry.is_file():
        os.replace(entry, entry.parent / filed_name(entry))

An assistant was asked to "tidy up the filenames in this folder, and don't overwrite anything". It produced this.

def tidy(folder):
    renamed = 0
    for entry in sorted(folder.iterdir()):
        target = folder / filed_name(entry)
        if target.exists():
            print(f"skipping {entry.name}, target exists")
            continue
        entry.rename(target)
        renamed += 1
    print(f"renamed {renamed} files")

def tidy(folder, apply_changes=False):
    moves, collisions = plan_renames(folder)
    if collisions:
        for target in collisions:
            print(f"refusing: more than one file wants the name {target}")
        return {"status": "refused", "collisions": collisions, "renamed": 0}
    if not apply_changes:
        return {"status": "planned", "collisions": [], "renamed": 0}
    for source, target in moves:
        os.replace(folder / source, folder / target)
    return {"status": "applied", "collisions": [], "renamed": len(moves)}

The starter builds two practice folders in the in-memory filesystem: messy, whose names collide once normalised, and clean, whose names do not. Write plan_renames and apply_renames. The plan must find the collision; the apply step must change nothing when there is one.

Loading this exercise…

Optional, and the transfer task for this lesson: handle the second kind of collision.

The plan above catches two sources aiming at one target. Give the folder an existing directory named ledger-2026.csv alongside the file Ledger 2026.csv. The planner filters out the directory, so it misses this occupied target. Extend plan_renames to report that conflict before applying anything. Then explain what happens when a target is already a file in the plan under this idempotent naming rule.

Sign in to track your progress on this exercise.

1. Why can a collision not be detected reliably one file at a time?
2. What does os.replace do when the target exists, and how does path.rename differ?
3. Why refuse the whole plan rather than skipping the colliding file?
4. Two files differ only by a space versus a hyphen. Why can they collide under this naming rule on both Windows and POSIX filesystems?

Sign in to track your progress on this exercise.

Compute every target before moving, group the plan by target to find names more than one source wants, and refuse a detected collision before any move. os.replace requests replacement consistently; protect other occupied targets and plan for failures before using it on real files. A multi-file loop is not atomic. Next: the other half of the duplicate problem, where two files have different names and identical contents, and the question is which copy to keep.