Bulk Change File Extensions

Overview

bulk-change-ext is a utility script to batch-rename file extensions (e.g., .png → .jpg) without modifying file contents.
It is generic, safe, and supports dry-run preview, recursive processing, and conflict handling.

Features

• 🔄 Rename any extension (not just .png → .jpg)

• 📂 Optional recursive mode (-r) to include subfolders

• 🔎 Dry-run mode to preview changes without touching files

• 🔒 Safe conflict handling: skip by default, or overwrite with --overwrite

• 🆚 Case-insensitive by default, with opt-in case-sensitive matching

• ✅ Deterministic order for reproducible results

Usage

Simple non-recursive, case-insensitive

poetry run bulk-change-ext ./assets/illustrations --from .png --to .jpg

Recursive, dry-run only

poetry run bulk-change-ext ./images --from png --to jpg -r --dry-run


#### Overwrite conflicts and use case-sensitive match
poetry run bulk-change-ext ./photos --from .PNG --to .jpeg --case-sensitive --overwrite

Overwrite conflicts and use case-sensitive match

poetry run bulk-change-ext ./photos --from .PNG --to .jpeg --case-sensitive --overwrite

CLI Options

Option	Description
directory	Target directory to process
--from EXT	Source extension (with/without dot)
--to EXT	Destination extension (with/without dot)
-r, --recursive	Recurse into subdirectories
--case-sensitive	Match extensions case-sensitively (default = insensitive)
--dry-run	Show what would be changed, but do nothing
--overwrite	Overwrite destination if it exists (default = skip)

Example

# Dry-run to preview
bulk-change-ext ./assets --from txt --to md --dry-run

# Actual rename
bulk-change-ext ./assets --from txt --to md

Test Coverage

Scenario	Test(s)
Happy path (.png → .jpg)	test_happy_path_png_to_jpg
Case-sensitive vs insensitive	test_case_sensitive_only_exact_match
Recursive processing	test_recursive_subdirs
Conflict handling (skip)	test_conflict_skips_when_overwrite_false
Conflict handling (overwrite)	test_conflict_overwrite_true
Dry-run behavior	test_dry_run_does_not_change_files
Missing directory	test_directory_does_not_exist_is_error
CLI smoke test	test_cli_smoke

---