tidybatch 1.1.1__tar.gz

tidybatch-1.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TidyBatch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tidybatch-1.1.1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: tidybatch
+Version: 1.1.1
+Summary: Bulk rename files safely: dry-run preview, collision-proof two-phase renames, one-command undo.
+Author: TidyBatch
+License: MIT
+Project-URL: Homepage, https://github.com/tidybatch/tidybatch
+Project-URL: Issues, https://github.com/tidybatch/tidybatch/issues
+Project-URL: TidyBatch Pro, https://whop.com/tidybatch/bulk-file-renamer/
+Keywords: rename,bulk-rename,batch-rename,files,cli,undo,dry-run
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# TidyBatch
+
+**Bulk rename files without the fear.** Preview every change, apply it, and undo it with one command.
+
+![TidyBatch demo: preview, apply, undo](https://raw.githubusercontent.com/tidybatch/tidybatch/main/docs/demo.gif)
+
+[![CI](https://github.com/tidybatch/tidybatch/actions/workflows/ci.yml/badge.svg)](https://github.com/tidybatch/tidybatch/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tidybatch)](https://pypi.org/project/tidybatch/)
+![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
+![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen)
+![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)
+
+Most bulk-rename scripts have a silent bug: renumber `1.txt 2.txt 3.txt` → `2.txt 3.txt 4.txt` and the first `mv` overwrites the original `2.txt`. TidyBatch is built around not doing that:
+
+- **Dry run by default.** Nothing changes until you add `--apply`.
+- **One-command undo.** Every applied run is journaled; `tidybatch undo <folder>` puts every file back.
+- **Never overwrites.** Two-phase renames make chains and swaps safe; clashes get `_1`, `_2`, …
+- **Case-insensitive collision checks**, because Windows and macOS treat `Photo.JPG` and `photo.jpg` as the same file.
+- **One file, standard library only.** No dependencies: you can read all of it before you trust it with your photos.
+
+New to bulk renaming? Read the tested guides at **[tidybatch.github.io/guides](https://tidybatch.github.io/guides/)**: how to rename safely on any OS, how to undo a bulk rename, and how to add dates to file names.
+
+## Install
+
+```bash
+pipx install tidybatch
+# or: uv tool install tidybatch
+# or: pip install tidybatch
+# or just download tidybatch.py and run: python3 tidybatch.py --help
+```
+
+Try it on a folder without installing anything permanent (it's a preview, so nothing changes):
+
+```bash
+uvx tidybatch rename ~/Downloads --slug --lower
+```
+
+## Recipes
+
+```bash
+# Clean names: no accents, spaces or symbols, all lowercase
+tidybatch rename ~/Downloads --slug --lower
+
+# Number photos in date order: holiday_001.jpg, holiday_002.jpg, …
+tidybatch rename ./photos -g "*.jpg" --sort date -t "holiday_{n:03}{ext}"
+
+# Put the file date in front: 2024-08-12_invoice.pdf
+tidybatch rename ./invoices -t "{date:%Y-%m-%d}_{stem}{ext}"
+
+# Name photos by when they were TAKEN (EXIF): 2023-07-14_182205.jpg
+tidybatch rename ./camera -t "{taken:%Y-%m-%d_%H%M%S}{ext}"
+
+# Regex with groups: IMG_2024_0001.jpg -> 2024-photo-0001.jpg
+tidybatch rename . --find "IMG_(\d{4})_(\d+)" --replace "\1-photo-\2"
+
+# Happy with the preview? Run it for real, then change your mind
+tidybatch rename ~/Downloads --slug --lower --apply
+tidybatch undo ~/Downloads
+```
+
+**Template fields:** `{stem}` `{ext}` `{n}` (counter, e.g. `{n:03}`) `{date}` (modification date, e.g. `{date:%Y%m%d}`) `{taken}` (photo **date taken** from EXIF, falling back to `{date}`) `{today}` `{parent}` `{size_kb}`
+
+**Options:** `-r` sub-folders · `-g "*.jpg"` filter · `--hidden` include hidden files · `--sort name|date|taken|size` · `--start N` · `--apply`
+
+**Photo dates:** `{taken}` reads EXIF with the standard library only, with no Pillow or exiftool needed. Every CI run checks it against ExifTool on ExifTool's own sample images (JPEG, HEIC, TIFF, DNG, CR2, CR3, NEF, RW2, RAF: same date for every file, [dev/verify_exif.py](https://github.com/tidybatch/tidybatch/blob/main/dev/verify_exif.py)) and feeds it 20,000 corrupted files, which must never crash or hang it ([dev/fuzz_exif.py](https://github.com/tidybatch/tidybatch/blob/main/dev/fuzz_exif.py)). Dates stored only in XMP/IPTC aren't read; those files fall back to the modification date.
+
+## How it stays safe
+
+1. **Plan:** compute every new name without touching the disk, then resolve collisions. A destination is free only if nobody else claimed it *and* whatever is there now is itself moving away.
+2. **Phase 1:** every file moves to a temporary name in the same folder.
+3. **Phase 2:** every temporary file moves to its final name, refusing to overwrite anything that appeared in the meantime.
+4. **Journal:** `<folder>/.tidybatch/journal-*.json` records each completed move, even if the run is interrupted, so `undo` can replay it backwards.
+
+## How it's made
+
+Most of the code was written with an AI coding agent. The behaviour that protects your files (two-phase moves, collision checks, undo) is pinned down by the test suite, which runs on Linux, macOS and Windows on every push.
+
+## TidyBatch Pro
+
+This repository is **TidyBatch Core** (rename + undo), free and MIT-licensed. **[TidyBatch Pro](https://whop.com/tidybatch/bulk-file-renamer/?utm_source=github&utm_campaign=tidybatch)** adds:
+
+- `organize`: sort a folder into Images / Documents / Videos…, by year/month (modified **or photo date taken**), or by extension
+- `dedupe`: find exact duplicates by content (SHA-256), keep the oldest, move the rest aside (never deleted)
+- ready-to-run apps for **Windows and Linux** (no Python needed), plus free 1.x updates
+
+Buying Pro also funds the free version. Thank you!
+
+## Contributing
+
+Bug reports with a reproducible folder layout are gold. Run the tests with:
+
+```bash
+python -m unittest discover -s tests
+
+# photo-date checks (needs perl and an ExifTool checkout)
+git clone --depth 1 https://github.com/exiftool/exiftool /tmp/exiftool
+python dev/verify_exif.py /tmp/exiftool
+python dev/fuzz_exif.py /tmp/exiftool
+```
+
+## License
+
+[MIT](https://github.com/tidybatch/tidybatch/blob/main/LICENSE)

tidybatch-1.1.1/README.md

@@ -0,0 +1,103 @@
+# TidyBatch
+
+**Bulk rename files without the fear.** Preview every change, apply it, and undo it with one command.
+
+![TidyBatch demo: preview, apply, undo](https://raw.githubusercontent.com/tidybatch/tidybatch/main/docs/demo.gif)
+
+[![CI](https://github.com/tidybatch/tidybatch/actions/workflows/ci.yml/badge.svg)](https://github.com/tidybatch/tidybatch/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tidybatch)](https://pypi.org/project/tidybatch/)
+![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
+![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen)
+![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)
+
+Most bulk-rename scripts have a silent bug: renumber `1.txt 2.txt 3.txt` → `2.txt 3.txt 4.txt` and the first `mv` overwrites the original `2.txt`. TidyBatch is built around not doing that:
+
+- **Dry run by default.** Nothing changes until you add `--apply`.
+- **One-command undo.** Every applied run is journaled; `tidybatch undo <folder>` puts every file back.
+- **Never overwrites.** Two-phase renames make chains and swaps safe; clashes get `_1`, `_2`, …
+- **Case-insensitive collision checks**, because Windows and macOS treat `Photo.JPG` and `photo.jpg` as the same file.
+- **One file, standard library only.** No dependencies: you can read all of it before you trust it with your photos.
+
+New to bulk renaming? Read the tested guides at **[tidybatch.github.io/guides](https://tidybatch.github.io/guides/)**: how to rename safely on any OS, how to undo a bulk rename, and how to add dates to file names.
+
+## Install
+
+```bash
+pipx install tidybatch
+# or: uv tool install tidybatch
+# or: pip install tidybatch
+# or just download tidybatch.py and run: python3 tidybatch.py --help
+```
+
+Try it on a folder without installing anything permanent (it's a preview, so nothing changes):
+
+```bash
+uvx tidybatch rename ~/Downloads --slug --lower
+```
+
+## Recipes
+
+```bash
+# Clean names: no accents, spaces or symbols, all lowercase
+tidybatch rename ~/Downloads --slug --lower
+
+# Number photos in date order: holiday_001.jpg, holiday_002.jpg, …
+tidybatch rename ./photos -g "*.jpg" --sort date -t "holiday_{n:03}{ext}"
+
+# Put the file date in front: 2024-08-12_invoice.pdf
+tidybatch rename ./invoices -t "{date:%Y-%m-%d}_{stem}{ext}"
+
+# Name photos by when they were TAKEN (EXIF): 2023-07-14_182205.jpg
+tidybatch rename ./camera -t "{taken:%Y-%m-%d_%H%M%S}{ext}"
+
+# Regex with groups: IMG_2024_0001.jpg -> 2024-photo-0001.jpg
+tidybatch rename . --find "IMG_(\d{4})_(\d+)" --replace "\1-photo-\2"
+
+# Happy with the preview? Run it for real, then change your mind
+tidybatch rename ~/Downloads --slug --lower --apply
+tidybatch undo ~/Downloads
+```
+
+**Template fields:** `{stem}` `{ext}` `{n}` (counter, e.g. `{n:03}`) `{date}` (modification date, e.g. `{date:%Y%m%d}`) `{taken}` (photo **date taken** from EXIF, falling back to `{date}`) `{today}` `{parent}` `{size_kb}`
+
+**Options:** `-r` sub-folders · `-g "*.jpg"` filter · `--hidden` include hidden files · `--sort name|date|taken|size` · `--start N` · `--apply`
+
+**Photo dates:** `{taken}` reads EXIF with the standard library only, with no Pillow or exiftool needed. Every CI run checks it against ExifTool on ExifTool's own sample images (JPEG, HEIC, TIFF, DNG, CR2, CR3, NEF, RW2, RAF: same date for every file, [dev/verify_exif.py](https://github.com/tidybatch/tidybatch/blob/main/dev/verify_exif.py)) and feeds it 20,000 corrupted files, which must never crash or hang it ([dev/fuzz_exif.py](https://github.com/tidybatch/tidybatch/blob/main/dev/fuzz_exif.py)). Dates stored only in XMP/IPTC aren't read; those files fall back to the modification date.
+
+## How it stays safe
+
+1. **Plan:** compute every new name without touching the disk, then resolve collisions. A destination is free only if nobody else claimed it *and* whatever is there now is itself moving away.
+2. **Phase 1:** every file moves to a temporary name in the same folder.
+3. **Phase 2:** every temporary file moves to its final name, refusing to overwrite anything that appeared in the meantime.
+4. **Journal:** `<folder>/.tidybatch/journal-*.json` records each completed move, even if the run is interrupted, so `undo` can replay it backwards.
+
+## How it's made
+
+Most of the code was written with an AI coding agent. The behaviour that protects your files (two-phase moves, collision checks, undo) is pinned down by the test suite, which runs on Linux, macOS and Windows on every push.
+
+## TidyBatch Pro
+
+This repository is **TidyBatch Core** (rename + undo), free and MIT-licensed. **[TidyBatch Pro](https://whop.com/tidybatch/bulk-file-renamer/?utm_source=github&utm_campaign=tidybatch)** adds:
+
+- `organize`: sort a folder into Images / Documents / Videos…, by year/month (modified **or photo date taken**), or by extension
+- `dedupe`: find exact duplicates by content (SHA-256), keep the oldest, move the rest aside (never deleted)
+- ready-to-run apps for **Windows and Linux** (no Python needed), plus free 1.x updates
+
+Buying Pro also funds the free version. Thank you!
+
+## Contributing
+
+Bug reports with a reproducible folder layout are gold. Run the tests with:
+
+```bash
+python -m unittest discover -s tests
+
+# photo-date checks (needs perl and an ExifTool checkout)
+git clone --depth 1 https://github.com/exiftool/exiftool /tmp/exiftool
+python dev/verify_exif.py /tmp/exiftool
+python dev/fuzz_exif.py /tmp/exiftool
+```
+
+## License
+
+[MIT](https://github.com/tidybatch/tidybatch/blob/main/LICENSE)

tidybatch-1.1.1/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tidybatch"
+dynamic = ["version"]
+description = "Bulk rename files safely: dry-run preview, collision-proof two-phase renames, one-command undo."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "TidyBatch" }]
+keywords = ["rename", "bulk-rename", "batch-rename", "files", "cli", "undo", "dry-run"]
+classifiers = [
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Filesystems",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/tidybatch/tidybatch"
+Issues = "https://github.com/tidybatch/tidybatch/issues"
+"TidyBatch Pro" = "https://whop.com/tidybatch/bulk-file-renamer/"
+
+[project.scripts]
+tidybatch = "tidybatch:main"
+
+[tool.setuptools]
+py-modules = ["tidybatch"]
+
+[tool.setuptools.dynamic]
+version = { attr = "tidybatch.__version__" }

tidybatch-1.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tidybatch-1.1.1/tests/test_tidybatch.py

@@ -0,0 +1,175 @@
+"""Run with:  python -m unittest discover -s tests  (from the product folder)."""
+from __future__ import annotations
+
+import io
+import os
+import sys
+import tempfile
+import time
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import tidybatch  # noqa: E402
+
+
+def run(*argv: str) -> int:
+    with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+        return tidybatch.main(list(argv))
+
+
+def jpeg_with_exif_date(when: str) -> bytes:
+    """Smallest JPEG-ish file whose APP1 segment carries EXIF DateTimeOriginal."""
+    import struct
+    tiff = b"II*\x00" + struct.pack("<I", 8)
+    tiff += struct.pack("<H", 1) + struct.pack("<HHII", 0x8769, 4, 1, 26) + struct.pack("<I", 0)
+    tiff += struct.pack("<H", 1) + struct.pack("<HHII", 0x9003, 2, 20, 44) + struct.pack("<I", 0)
+    tiff += when.encode("ascii") + b"\x00"
+    payload = b"Exif\x00\x00" + tiff
+    return b"\xff\xd8" + b"\xff\xe1" + struct.pack(">H", len(payload) + 2) + payload + b"\xff\xd9"
+
+
+class TidyBatchTest(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self._tmp.name)
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def make(self, rel: str, content: str = "x", age: float = 0) -> Path:
+        p = self.root / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content)
+        if age:
+            t = time.time() - age
+            os.utime(p, (t, t))
+        return p
+
+    def names(self, folder: Path | None = None) -> set[str]:
+        folder = folder or self.root
+        return {str(p.relative_to(folder)) for p in folder.rglob("*")
+                if p.is_file() and tidybatch.JOURNAL_DIR not in p.parts}
+
+    def make_photo(self, rel: str, taken: str, age: float = 0) -> Path:
+        p = self.root / rel
+        p.write_bytes(jpeg_with_exif_date(taken))
+        if age:
+            t = time.time() - age
+            os.utime(p, (t, t))
+        return p
+
+    def test_taken_date_reads_exif(self):
+        p = self.make_photo("a.jpg", "2021:05:06 07:08:09")
+        self.assertEqual(str(tidybatch.taken_date(p)), "2021-05-06 07:08:09")
+
+    def test_taken_template_uses_exif_not_mtime(self):
+        self.make_photo("IMG_1.jpg", "2019:12:31 23:59:59")
+        run("rename", str(self.root), "-t", "{taken:%Y-%m-%d_%H%M%S}{ext}", "--apply")
+        self.assertEqual(self.names(), {"2019-12-31_235959.jpg"})
+
+    def test_taken_falls_back_to_mtime(self):
+        self.make("notes.txt")
+        p = self.root / "notes.txt"
+        t = time.mktime((2020, 2, 3, 12, 0, 0, 0, 0, -1)); os.utime(p, (t, t))
+        run("rename", str(self.root), "-t", "{taken:%Y-%m-%d}_{stem}{ext}", "--apply")
+        self.assertEqual(self.names(), {"2020-02-03_notes.txt"})
+
+    def test_garbage_file_has_no_taken_date(self):
+        p = self.root / "broken.jpg"
+        p.write_bytes(b"\xff\xd8\xff\xe1\x00")
+        self.assertIsNone(tidybatch.taken_date(p))
+
+    def test_sort_taken_orders_by_photo_date(self):
+        self.make_photo("b.jpg", "2020:01:01 10:00:00")
+        self.make_photo("a.jpg", "2021:01:01 10:00:00")
+        run("rename", str(self.root), "--sort", "taken", "-t", "{n}{ext}", "--apply")
+        self.assertEqual(tidybatch.taken_date(self.root / "1.jpg").year, 2020)
+
+    def test_dry_run_changes_nothing(self):
+        self.make("My File.TXT")
+        self.assertEqual(run("rename", str(self.root), "--slug", "--lower"), 0)
+        self.assertEqual(self.names(), {"My File.TXT"})
+
+    def test_slug_and_undo_round_trip(self):
+        self.make("Relatório Final (v2).PDF")
+        self.make("Foto Férias 01.JPG")
+        before = self.names()
+        run("rename", str(self.root), "--slug", "--lower", "--apply")
+        self.assertEqual(self.names(), {"relatorio_final_v2.pdf", "foto_ferias_01.jpg"})
+        run("undo", str(self.root))
+        self.assertEqual(self.names(), before)
+
+    def test_numbering_chain_does_not_clobber(self):
+        # 1->2, 2->3, 3->4: a naive renamer overwrites file 2 with file 1.
+        for i in (1, 2, 3):
+            self.make(f"{i}.txt", content=f"content-{i}")
+        run("rename", str(self.root), "-t", "{n}{ext}", "--start", "2", "--apply")
+        self.assertEqual(self.names(), {"2.txt", "3.txt", "4.txt"})
+        self.assertEqual((self.root / "4.txt").read_text(), "content-3")
+        self.assertEqual((self.root / "2.txt").read_text(), "content-1")
+
+    def test_collisions_get_suffix(self):
+        self.make("a b.txt", "1")
+        self.make("a_b.txt", "2")  # already the slug of the first one
+        run("rename", str(self.root), "--slug", "--apply")
+        self.assertEqual(self.names(), {"a_b.txt", "a_b_1.txt"})
+        self.assertEqual((self.root / "a_b.txt").read_text(), "2")
+
+    def test_find_replace_with_groups(self):
+        self.make("IMG_2024_0001.jpg")
+        run("rename", str(self.root), "--find", r"IMG_(\d{4})_(\d+)", "--replace", r"\1-photo-\2", "--apply")
+        self.assertEqual(self.names(), {"2024-photo-0001.jpg"})
+
+    def test_natural_sort_numbering(self):
+        for name in ("img10.png", "img2.png", "img1.png"):
+            self.make(name, content=name)
+        run("rename", str(self.root), "-t", "{n:02}{ext}", "--apply")
+        self.assertEqual((self.root / "02.png").read_text(), "img2.png")
+        self.assertEqual((self.root / "03.png").read_text(), "img10.png")
+
+    def test_summary_wording_matches_mode(self):
+        self.make("A B.txt")
+        out = io.StringIO()
+        with redirect_stdout(out):
+            tidybatch.main(["rename", str(self.root), "--slug"])
+        self.assertIn("1 file(s) would change.", out.getvalue())
+        out = io.StringIO()
+        with redirect_stdout(out):
+            tidybatch.main(["rename", str(self.root), "--slug", "--apply"])
+        self.assertIn("1 file(s) will change.", out.getvalue())
+
+    def test_unicode_normalization_counts_as_collision(self):
+        # 'é' precomposed (NFC) vs 'e' + combining accent (NFD): one file on macOS.
+        a, b = self.make("a.txt"), self.make("b.txt")
+        moves = tidybatch.resolve_collisions([
+            tidybatch.Move(a, self.root / "caf\u00e9.txt"),
+            tidybatch.Move(b, self.root / "cafe\u0301.txt"),
+        ])
+        self.assertEqual(moves[1].dst.name, "cafe\u0301_1.txt")
+
+    def test_pro_commands_point_to_pro_without_touching_files(self):
+        self.make("a b.txt")
+        for argv in (["organize", str(self.root), "--apply"], ["dedupe", str(self.root)]):
+            out, err = io.StringIO(), io.StringIO()
+            with redirect_stdout(out), redirect_stderr(err):
+                code = tidybatch.main(argv)
+            # A script must not mistake "not in Core" for success.
+            self.assertEqual(code, 2)
+            self.assertIn("TidyBatch Pro", err.getvalue())
+            self.assertEqual(out.getvalue(), "")
+        self.assertEqual(self.names(), {"a b.txt"})
+
+    def test_bad_template_is_a_clean_error(self):
+        self.make("a.txt")
+        self.assertEqual(run("rename", str(self.root), "-t", "{nope}"), 2)
+
+    def test_template_cannot_create_paths(self):
+        self.make("a.txt")
+        self.assertEqual(run("rename", str(self.root), "-t", "../{stem}{ext}", "--apply"), 2)
+        self.assertEqual(self.names(), {"a.txt"})
+
+
+if __name__ == "__main__":
+    unittest.main()

tidybatch-1.1.1/tidybatch.egg-info/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: tidybatch
+Version: 1.1.1
+Summary: Bulk rename files safely: dry-run preview, collision-proof two-phase renames, one-command undo.
+Author: TidyBatch
+License: MIT
+Project-URL: Homepage, https://github.com/tidybatch/tidybatch
+Project-URL: Issues, https://github.com/tidybatch/tidybatch/issues
+Project-URL: TidyBatch Pro, https://whop.com/tidybatch/bulk-file-renamer/
+Keywords: rename,bulk-rename,batch-rename,files,cli,undo,dry-run
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# TidyBatch
+
+**Bulk rename files without the fear.** Preview every change, apply it, and undo it with one command.
+
+![TidyBatch demo: preview, apply, undo](https://raw.githubusercontent.com/tidybatch/tidybatch/main/docs/demo.gif)
+
+[![CI](https://github.com/tidybatch/tidybatch/actions/workflows/ci.yml/badge.svg)](https://github.com/tidybatch/tidybatch/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tidybatch)](https://pypi.org/project/tidybatch/)
+![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
+![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen)
+![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)
+
+Most bulk-rename scripts have a silent bug: renumber `1.txt 2.txt 3.txt` → `2.txt 3.txt 4.txt` and the first `mv` overwrites the original `2.txt`. TidyBatch is built around not doing that:
+
+- **Dry run by default.** Nothing changes until you add `--apply`.
+- **One-command undo.** Every applied run is journaled; `tidybatch undo <folder>` puts every file back.
+- **Never overwrites.** Two-phase renames make chains and swaps safe; clashes get `_1`, `_2`, …
+- **Case-insensitive collision checks**, because Windows and macOS treat `Photo.JPG` and `photo.jpg` as the same file.
+- **One file, standard library only.** No dependencies: you can read all of it before you trust it with your photos.
+
+New to bulk renaming? Read the tested guides at **[tidybatch.github.io/guides](https://tidybatch.github.io/guides/)**: how to rename safely on any OS, how to undo a bulk rename, and how to add dates to file names.
+
+## Install
+
+```bash
+pipx install tidybatch
+# or: uv tool install tidybatch
+# or: pip install tidybatch
+# or just download tidybatch.py and run: python3 tidybatch.py --help
+```
+
+Try it on a folder without installing anything permanent (it's a preview, so nothing changes):
+
+```bash
+uvx tidybatch rename ~/Downloads --slug --lower
+```
+
+## Recipes
+
+```bash
+# Clean names: no accents, spaces or symbols, all lowercase
+tidybatch rename ~/Downloads --slug --lower
+
+# Number photos in date order: holiday_001.jpg, holiday_002.jpg, …
+tidybatch rename ./photos -g "*.jpg" --sort date -t "holiday_{n:03}{ext}"
+
+# Put the file date in front: 2024-08-12_invoice.pdf
+tidybatch rename ./invoices -t "{date:%Y-%m-%d}_{stem}{ext}"
+
+# Name photos by when they were TAKEN (EXIF): 2023-07-14_182205.jpg
+tidybatch rename ./camera -t "{taken:%Y-%m-%d_%H%M%S}{ext}"
+
+# Regex with groups: IMG_2024_0001.jpg -> 2024-photo-0001.jpg
+tidybatch rename . --find "IMG_(\d{4})_(\d+)" --replace "\1-photo-\2"
+
+# Happy with the preview? Run it for real, then change your mind
+tidybatch rename ~/Downloads --slug --lower --apply
+tidybatch undo ~/Downloads
+```
+
+**Template fields:** `{stem}` `{ext}` `{n}` (counter, e.g. `{n:03}`) `{date}` (modification date, e.g. `{date:%Y%m%d}`) `{taken}` (photo **date taken** from EXIF, falling back to `{date}`) `{today}` `{parent}` `{size_kb}`
+
+**Options:** `-r` sub-folders · `-g "*.jpg"` filter · `--hidden` include hidden files · `--sort name|date|taken|size` · `--start N` · `--apply`
+
+**Photo dates:** `{taken}` reads EXIF with the standard library only, with no Pillow or exiftool needed. Every CI run checks it against ExifTool on ExifTool's own sample images (JPEG, HEIC, TIFF, DNG, CR2, CR3, NEF, RW2, RAF: same date for every file, [dev/verify_exif.py](https://github.com/tidybatch/tidybatch/blob/main/dev/verify_exif.py)) and feeds it 20,000 corrupted files, which must never crash or hang it ([dev/fuzz_exif.py](https://github.com/tidybatch/tidybatch/blob/main/dev/fuzz_exif.py)). Dates stored only in XMP/IPTC aren't read; those files fall back to the modification date.
+
+## How it stays safe
+
+1. **Plan:** compute every new name without touching the disk, then resolve collisions. A destination is free only if nobody else claimed it *and* whatever is there now is itself moving away.
+2. **Phase 1:** every file moves to a temporary name in the same folder.
+3. **Phase 2:** every temporary file moves to its final name, refusing to overwrite anything that appeared in the meantime.
+4. **Journal:** `<folder>/.tidybatch/journal-*.json` records each completed move, even if the run is interrupted, so `undo` can replay it backwards.
+
+## How it's made
+
+Most of the code was written with an AI coding agent. The behaviour that protects your files (two-phase moves, collision checks, undo) is pinned down by the test suite, which runs on Linux, macOS and Windows on every push.
+
+## TidyBatch Pro
+
+This repository is **TidyBatch Core** (rename + undo), free and MIT-licensed. **[TidyBatch Pro](https://whop.com/tidybatch/bulk-file-renamer/?utm_source=github&utm_campaign=tidybatch)** adds:
+
+- `organize`: sort a folder into Images / Documents / Videos…, by year/month (modified **or photo date taken**), or by extension
+- `dedupe`: find exact duplicates by content (SHA-256), keep the oldest, move the rest aside (never deleted)
+- ready-to-run apps for **Windows and Linux** (no Python needed), plus free 1.x updates
+
+Buying Pro also funds the free version. Thank you!
+
+## Contributing
+
+Bug reports with a reproducible folder layout are gold. Run the tests with:
+
+```bash
+python -m unittest discover -s tests
+
+# photo-date checks (needs perl and an ExifTool checkout)
+git clone --depth 1 https://github.com/exiftool/exiftool /tmp/exiftool
+python dev/verify_exif.py /tmp/exiftool
+python dev/fuzz_exif.py /tmp/exiftool
+```
+
+## License
+
+[MIT](https://github.com/tidybatch/tidybatch/blob/main/LICENSE)

tidybatch-1.1.1/tidybatch.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+tidybatch.py
+tests/test_tidybatch.py
+tidybatch.egg-info/PKG-INFO
+tidybatch.egg-info/SOURCES.txt
+tidybatch.egg-info/dependency_links.txt
+tidybatch.egg-info/entry_points.txt
+tidybatch.egg-info/top_level.txt

tidybatch-1.1.1/tidybatch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tidybatch-1.1.1/tidybatch.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tidybatch = tidybatch:main

tidybatch-1.1.1/tidybatch.egg-info/top_level.txt

@@ -0,0 +1 @@
+tidybatch

tidybatch-1.1.1/tidybatch.py

@@ -0,0 +1,604 @@
+#!/usr/bin/env python3
+"""
+TidyBatch Core - bulk rename files safely, with preview and one-command undo.
+
+Safety model:
+  * Every command is a DRY RUN unless you pass --apply.
+  * Every applied run writes a journal to <folder>/.tidybatch/,
+    so `tidybatch undo <folder>` puts every file back where it was.
+  * Nothing is ever deleted or overwritten.
+  * Name collisions are resolved with a numeric suffix, never by overwriting.
+
+Standard library only (Python 3.9+). MIT licensed.
+
+`organize` and `dedupe` are part of TidyBatch Pro: https://whop.com/tidybatch/bulk-file-renamer/
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import struct
+import sys
+import unicodedata
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Iterable, Iterator
+
+__version__ = "1.1.1"
+
+JOURNAL_DIR = ".tidybatch"
+TMP_PREFIX = ".tidybatch-tmp-"
+SKIP_DIRS = {JOURNAL_DIR, "_duplicates", ".git", "__pycache__"}
+
+class TidyError(Exception):
+    """A user-facing error: printed without a traceback."""
+
+
+@dataclass(frozen=True)
+class Move:
+    src: Path
+    dst: Path
+
+
+# --------------------------------------------------------------------------- #
+# File discovery
+# --------------------------------------------------------------------------- #
+
+def iter_files(root: Path, recursive: bool, glob: str | None, include_hidden: bool) -> Iterator[Path]:
+    """Yield regular files under root, skipping TidyBatch's own folders."""
+    if recursive:
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and (include_hidden or not d.startswith("."))]
+            for name in filenames:
+                p = Path(dirpath) / name
+                if _wanted(p, glob, include_hidden):
+                    yield p
+    else:
+        for p in root.iterdir():
+            if p.is_file() and _wanted(p, glob, include_hidden):
+                yield p
+
+
+def _wanted(p: Path, glob: str | None, include_hidden: bool) -> bool:
+    if p.name.startswith(TMP_PREFIX) or p.is_symlink():
+        return False
+    if not include_hidden and p.name.startswith("."):
+        return False
+    return glob is None or p.match(glob)
+
+
+def natural_key(p: Path) -> list:
+    """Sort 'img2' before 'img10', the way humans expect."""
+    return [int(t) if t.isdigit() else t for t in re.split(r"(\d+)", p.name.casefold())]
+
+
+def sort_files(files: Iterable[Path], by: str) -> list[Path]:
+    if by == "taken":
+        return sorted(files, key=lambda p: (taken_or_mtime(p), natural_key(p)))
+    if by == "date":
+        return sorted(files, key=lambda p: (p.stat().st_mtime, natural_key(p)))
+    if by == "size":
+        return sorted(files, key=lambda p: (p.stat().st_size, natural_key(p)))
+    return sorted(files, key=natural_key)
+
+
+# --------------------------------------------------------------------------- #
+# Photo dates (EXIF "date taken"), standard library only.
+# JPEG, TIFF, TIFF-based RAW (DNG, CR2, NEF, ARW, ORF, RW2), Fuji RAF, Canon CR3
+# and HEIC/HEIF/AVIF. Checked against ExifTool's sample images; see dev/.
+# --------------------------------------------------------------------------- #
+
+_TIFF_MAGIC = {42, 0x4F52, 0x5352, 0x55}  # TIFF, Olympus ORF (x2), Panasonic RW2
+_DATE_TAGS = (0x9003, 0x9004, 0x0132)     # DateTimeOriginal, DateTimeDigitized, DateTime
+
+
+def taken_date(path: Path) -> datetime | None:
+    """EXIF DateTimeOriginal, else DateTimeDigitized, else IFD0 DateTime; None if absent."""
+    try:
+        with path.open("rb") as f:
+            head = f.read(16)
+            if head[:2] == b"\xff\xd8":
+                base = _jpeg_tiff_offset(f, 0)
+            elif head[:4] in (b"II*\x00", b"MM\x00*", b"IIRO", b"IIRS", b"IIU\x00"):
+                base = 0
+            elif head.startswith(b"FUJIFILMCCD-RAW"):
+                f.seek(84)
+                jpeg_at = struct.unpack(">I", f.read(4))[0]
+                base = _jpeg_tiff_offset(f, jpeg_at)
+            elif head[4:12] == b"ftypcrx ":
+                return _cr3_date(f)
+            elif head[4:8] == b"ftyp":
+                base = _isobmff_tiff_offset(f)
+            else:
+                return None
+            return _tiff_date(f, base) if base is not None else None
+    except Exception:  # metadata is best-effort: a broken file must never stop a rename
+        return None
+
+
+def _cr3_date(f) -> datetime | None:
+    """Canon CR3: EXIF lives in 'CMT1' (IFD0) and 'CMT2' (Exif IFD) boxes, each a TIFF."""
+    f.seek(0)
+    head = f.read(1 << 18)
+    for box in (b"CMT2", b"CMT1"):
+        i = head.find(box)
+        if i >= 4:
+            d = _tiff_date(f, i + 4, exif_ifd_at_root=(box == b"CMT2"))
+            if d:
+                return d
+    return None
+
+
+def _jpeg_tiff_offset(f, start: int) -> int | None:
+    """Offset of the TIFF header inside a JPEG's 'Exif' APP1 segment."""
+    pos = start + 2
+    for _ in range(1000):
+        f.seek(pos)
+        marker = f.read(2)
+        if len(marker) < 2 or marker[0] != 0xFF:
+            return None
+        m = marker[1]
+        if m == 0xFF:              # fill byte
+            pos += 1
+            continue
+        if m in (0xD9, 0xDA):      # end of image / start of scan: no EXIF before pixels
+            return None
+        if 0xD0 <= m <= 0xD7 or m == 0x01:
+            pos += 2
+            continue
+        seglen = struct.unpack(">H", f.read(2))[0]
+        if m == 0xE1 and f.read(6) == b"Exif\x00\x00":
+            return pos + 10
+        pos += 2 + seglen
+    return None
+
+
+def _boxes(f, start: int, end: int):
+    pos = start
+    while pos + 8 <= end:
+        f.seek(pos)
+        size, btype = struct.unpack(">I4s", f.read(8))
+        hdr = 8
+        if size == 1:
+            size = struct.unpack(">Q", f.read(8))[0]
+            hdr = 16
+        elif size == 0:
+            size = end - pos
+        if size < hdr:
+            return
+        yield btype, pos, size, hdr
+        pos += size
+
+
+def _isobmff_tiff_offset(f) -> int | None:
+    """HEIC/HEIF/AVIF: locate the 'Exif' item via meta/iinf + meta/iloc."""
+    f.seek(0, 2)
+    file_end = f.tell()
+    meta = next(((p + h + 4, p + s) for t, p, s, h in _boxes(f, 0, file_end) if t == b"meta"), None)
+    if not meta:
+        return None
+    exif_id, iloc = None, None
+    for btype, p, s, h in _boxes(f, *meta):
+        if btype == b"iinf":
+            exif_id = _iinf_exif_id(f, p + h, p + s)
+        elif btype == b"iloc":
+            iloc = (p + h, p + s)
+    if exif_id is None or iloc is None:
+        return None
+    loc = _iloc_offset(f, iloc[0], exif_id)
+    if loc is None:
+        return None
+    f.seek(loc)
+    tiff = loc + 4 + struct.unpack(">I", f.read(4))[0]
+    f.seek(tiff)
+    if f.read(2) not in (b"II", b"MM"):           # some writers point at "Exif\0\0"
+        f.seek(loc)
+        blob = f.read(32)
+        i = blob.find(b"Exif\x00\x00")
+        tiff = loc + i + 6 if i >= 0 else None
+    return tiff
+
+
+def _iinf_exif_id(f, start: int, end: int) -> int | None:
+    f.seek(start)
+    version = f.read(4)[0]
+    f.read(2 if version == 0 else 4)               # entry_count
+    for btype, p, s, h in _boxes(f, f.tell(), end):
+        if btype != b"infe":
+            continue
+        f.seek(p + h)
+        v = f.read(4)[0]
+        if v < 2:
+            continue
+        item_id = struct.unpack(">H" if v == 2 else ">I", f.read(2 if v == 2 else 4))[0]
+        f.read(2)                                   # protection index
+        if f.read(4) == b"Exif":
+            return item_id
+    return None
+
+
+def _uint(f, size: int) -> int:
+    return int.from_bytes(f.read(size), "big") if size else 0
+
+
+def _iloc_offset(f, start: int, wanted: int) -> int | None:
+    f.seek(start)
+    version = f.read(4)[0]
+    b1, b2 = f.read(2)
+    off_size, len_size, base_size = b1 >> 4, b1 & 15, b2 >> 4
+    idx_size = b2 & 15 if version in (1, 2) else 0
+    count = _uint(f, 2 if version < 2 else 4)
+    if count > 4096:
+        return None
+    for _ in range(count):
+        item_id = _uint(f, 2 if version < 2 else 4)
+        method = _uint(f, 2) & 15 if version in (1, 2) else 0
+        f.read(2)                                   # data reference index
+        base = _uint(f, base_size)
+        extents = _uint(f, 2)
+        if extents > 4096:
+            return None
+        first = None
+        for _ in range(extents):
+            _uint(f, idx_size)
+            off = _uint(f, off_size)
+            _uint(f, len_size)
+            if first is None:
+                first = off
+        if item_id == wanted:
+            return base + (first or 0) if method == 0 else None
+    return None
+
+
+def _tiff_date(f, base: int, exif_ifd_at_root: bool = False) -> datetime | None:
+    f.seek(base)
+    hdr = f.read(8)
+    if hdr[:2] == b"II":
+        e = "<"
+    elif hdr[:2] == b"MM":
+        e = ">"
+    else:
+        return None
+    magic, ifd0 = struct.unpack(e + "HI", hdr[2:8])
+    if magic not in _TIFF_MAGIC:
+        return None
+    found: dict[int, tuple] = {}
+    exif_ifd = None
+    for tag, typ, count, raw in _ifd(f, base, ifd0, e):
+        if exif_ifd_at_root and tag in (0x9003, 0x9004):
+            found[tag] = (typ, count, raw)
+        elif tag == 0x8769:
+            exif_ifd = struct.unpack(e + "I", raw)[0]
+        elif tag == 0x0132:
+            found[tag] = (typ, count, raw)
+    if exif_ifd:
+        for tag, typ, count, raw in _ifd(f, base, exif_ifd, e):
+            if tag in (0x9003, 0x9004):
+                found[tag] = (typ, count, raw)
+    for tag in _DATE_TAGS:
+        if tag in found:
+            d = _ascii_date(f, base, e, *found[tag])
+            if d:
+                return d
+    return None
+
+
+def _ifd(f, base: int, offset: int, e: str):
+    f.seek(base + offset)
+    n = struct.unpack(e + "H", f.read(2))[0]
+    if n > 1000:
+        return
+    data = f.read(12 * n)
+    for i in range(n):
+        entry = data[12 * i:12 * i + 12]
+        if len(entry) < 12:
+            return
+        tag, typ, count = struct.unpack(e + "HHI", entry[:8])
+        yield tag, typ, count, entry[8:12]
+
+
+def _ascii_date(f, base: int, e: str, typ: int, count: int, raw: bytes) -> datetime | None:
+    if typ != 2 or count < 19:
+        return None
+    f.seek(base + struct.unpack(e + "I", raw)[0])
+    text = f.read(min(count, 32)).split(b"\x00")[0].decode("ascii", "ignore").strip()
+    for fmt in ("%Y:%m:%d %H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y:%m:%d %H:%M"):
+        try:
+            return datetime.strptime(text[:19] if "S" in fmt else text[:16], fmt)
+        except ValueError:
+            continue
+    return None
+
+
+def taken_or_mtime(path: Path) -> datetime:
+    """Photo 'date taken' when the file has one, otherwise its modification time."""
+    return taken_date(path) or datetime.fromtimestamp(path.stat().st_mtime)
+
+
+# --------------------------------------------------------------------------- #
+# Naming helpers
+# --------------------------------------------------------------------------- #
+
+_INVALID_CHARS = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+
+
+def slugify(text: str, lower: bool = True, sep: str = "_") -> str:
+    """'Relatório Final (v2)' -> 'relatorio_final_v2'. Safe on every OS."""
+    text = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode("ascii")
+    text = re.sub(r"[^\w.-]+", sep, text)
+    text = re.sub(rf"{re.escape(sep)}{{2,}}", sep, text).strip(sep + ".")
+    return text.lower() if lower else text
+
+
+def render_name(template: str, path: Path, index: int, stem: str | None = None) -> str:
+    stat = path.stat()
+    fields = {
+        "stem": path.stem if stem is None else stem,
+        "ext": path.suffix,
+        "n": index,
+        "date": datetime.fromtimestamp(stat.st_mtime),
+        # Reading EXIF costs a file read, so only do it when the template asks.
+        "taken": taken_or_mtime(path) if "{taken" in template else None,
+        "today": datetime.now(),
+        "parent": path.parent.name,
+        "size_kb": stat.st_size // 1024,
+    }
+    try:
+        name = template.format(**fields)
+    except KeyError as e:
+        raise TidyError(f"Unknown template field {e}. Available: {', '.join('{' + k + '}' for k in fields)}")
+    except (ValueError, IndexError) as e:
+        raise TidyError(f"Invalid template '{template}': {e}")
+    if "/" in name or "\\" in name:
+        raise TidyError("Template must produce a file name, not a path (no '/' or '\\').")
+    return name
+
+
+def _key(p: Path) -> str:
+    # Case- and normalization-insensitive on purpose: Windows and macOS file
+    # systems treat 'A.txt'/'a.txt' (and composed/decomposed 'é') as the same
+    # file, so we must too.
+    return unicodedata.normalize("NFC", str(p)).casefold()
+
+
+def resolve_collisions(moves: list[Move]) -> list[Move]:
+    """
+    Make every destination unique. A destination is free if nobody else
+    already claimed it in this plan and either nothing is there on disk, or
+    whatever is there is itself being moved away by this plan.
+    """
+    active = [m for m in moves if m.src != m.dst]
+    leaving = {_key(m.src) for m in active}
+    # Files that keep their name still occupy it.
+    claimed = {_key(m.src) for m in moves if m.src == m.dst}
+    result = []
+    for m in active:
+        dst, i = m.dst, 1
+        # A case-only rename (Photo.JPG -> photo.jpg) passes: its own src is "leaving".
+        while _key(dst) in claimed or (dst.exists() and _key(dst) not in leaving):
+            dst = m.dst.with_name(f"{m.dst.stem}_{i}{m.dst.suffix}")
+            i += 1
+        claimed.add(_key(dst))
+        result.append(Move(m.src, dst))
+    return result
+
+
+# --------------------------------------------------------------------------- #
+# Planners: they only compute moves, never touch the disk
+# --------------------------------------------------------------------------- #
+
+def plan_rename(files: list[Path], template: str, find: str | None, replace: str,
+                slug: bool, lower: bool, start: int) -> list[Move]:
+    pattern = None
+    if find:
+        try:
+            pattern = re.compile(find)
+        except re.error as e:
+            raise TidyError(f"Invalid --find regex: {e}")
+
+    moves = []
+    for index, path in enumerate(files, start=start):
+        stem = pattern.sub(replace, path.stem) if pattern else path.stem
+        name = render_name(template, path, index, stem)
+        if slug or lower:
+            p = Path(name)
+            stem = slugify(p.stem, lower=lower) if slug else p.stem.lower()
+            name = (stem or "file") + (p.suffix.lower() if lower else p.suffix)
+        name = _INVALID_CHARS.sub("_", name).strip() or f"file{path.suffix}"
+        moves.append(Move(path, path.with_name(name)))
+    return resolve_collisions(moves)
+
+
+# --------------------------------------------------------------------------- #
+# Execution + journal
+# --------------------------------------------------------------------------- #
+
+def apply_moves(moves: list[Move], root: Path) -> Path:
+    """
+    Two-phase move: every source first goes to a temporary name, then to its
+    final name. This makes chains and swaps safe (a->b while b->c, or a<->b).
+    The journal is written even if something fails halfway.
+    """
+    journal_dir = root / JOURNAL_DIR
+    journal_dir.mkdir(exist_ok=True)
+    journal = journal_dir / f"journal-{datetime.now():%Y%m%d-%H%M%S-%f}.json"
+
+    staged: list[tuple[Move, Path]] = []
+    done: list[Move] = []
+    try:
+        for i, m in enumerate(moves):
+            tmp = m.src.with_name(f"{TMP_PREFIX}{os.getpid()}-{i}{m.src.suffix}")
+            os.rename(m.src, tmp)
+            staged.append((m, tmp))
+        for m, tmp in staged:
+            if m.dst.exists():
+                raise TidyError(f"Refusing to overwrite '{m.dst}' (it appeared during the run).")
+            m.dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.move(str(tmp), str(m.dst))
+            done.append(m)
+    except BaseException:
+        finished = {id(m) for m in done}
+        for m, tmp in staged:
+            if id(m) not in finished and tmp.exists():
+                os.rename(tmp, m.src)
+        raise
+    finally:
+        if done:
+            payload = {
+                "version": __version__,
+                "root": str(root.resolve()),
+                "created": datetime.now().isoformat(timespec="seconds"),
+                "moves": [{"src": str(m.src.resolve()), "dst": str(m.dst.resolve())} for m in done],
+            }
+            journal.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    return journal
+
+
+def undo(root: Path, journal_path: Path | None) -> int:
+    journal_dir = root / JOURNAL_DIR
+    if journal_path is None:
+        journals = sorted(journal_dir.glob("journal-*.json")) if journal_dir.is_dir() else []
+        if not journals:
+            raise TidyError(f"No journal found in '{journal_dir}'. Nothing to undo.")
+        journal_path = journals[-1]
+
+    data = json.loads(journal_path.read_text(encoding="utf-8"))
+    journal_root = Path(data["root"])
+    restored = skipped = 0
+    for entry in reversed(data["moves"]):
+        src, dst = Path(entry["src"]), Path(entry["dst"])
+        if not dst.exists():
+            print(f"  skip (missing now): {dst}")
+            skipped += 1
+            continue
+        if src.exists() and _key(src) != _key(dst):
+            print(f"  skip (original name taken): {src}")
+            skipped += 1
+            continue
+        src.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(dst), str(src))
+        _remove_empty_parents(dst.parent, stop_at=journal_root)
+        restored += 1
+
+    journal_path.rename(journal_path.with_suffix(".undone"))
+    print(f"Restored {restored} file(s), skipped {skipped}. Journal: {journal_path.name}")
+    return 0 if skipped == 0 else 1
+
+
+def _remove_empty_parents(folder: Path, stop_at: Path) -> None:
+    folder, stop_at = folder.resolve(), stop_at.resolve()
+    while folder != stop_at and stop_at in folder.parents:
+        try:
+            folder.rmdir()  # only succeeds when empty
+        except OSError:
+            return
+        folder = folder.parent
+
+
+# --------------------------------------------------------------------------- #
+# CLI
+# --------------------------------------------------------------------------- #
+
+def show_plan(moves: list[Move], root: Path, applying: bool = False) -> None:
+    def rel(p: Path) -> str:
+        try:
+            return str(p.relative_to(root))
+        except ValueError:
+            return str(p)
+
+    if not moves:
+        print("Nothing to do: every file already matches.")
+        return
+    width = min(max(len(rel(m.src)) for m in moves), 60)
+    for m in moves:
+        print(f"  {rel(m.src):<{width}}  ->  {rel(m.dst)}")
+    print(f"\n{len(moves)} file(s) {'will change' if applying else 'would change'}.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("folder", type=Path, help="folder to work on")
+    common.add_argument("-r", "--recursive", action="store_true", help="include sub-folders")
+    common.add_argument("-g", "--glob", help="only files matching this pattern, e.g. '*.jpg'")
+    common.add_argument("--hidden", action="store_true", help="include hidden files")
+    common.add_argument("--apply", action="store_true", help="actually do it (default is a dry run)")
+
+    parser = argparse.ArgumentParser(
+        prog="tidybatch",
+        description="Bulk rename files safely. Dry run by default; every change can be undone.",
+        epilog="Need to sort folders or remove duplicates? TidyBatch Pro adds `organize` and `dedupe`: https://whop.com/tidybatch/bulk-file-renamer/",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    r = sub.add_parser("rename", parents=[common], help="rename files from a template",
+                       description="Template fields: {stem} {ext} {n} {date} {taken} {today} {parent} {size_kb}. "
+                                   "{date} is the modification time; {taken} is the photo's EXIF date taken "
+                                   "(falls back to {date}). Formats work: {n:03}, {taken:%Y-%m-%d}.")
+    r.add_argument("-t", "--template", default="{stem}{ext}", help="new name template (default: {stem}{ext})")
+    r.add_argument("--find", help="regex to search in the original name (without extension)")
+    r.add_argument("--replace", default="", help="replacement for --find (supports \\1 groups)")
+    r.add_argument("--slug", action="store_true", help="remove accents, spaces and symbols")
+    r.add_argument("--lower", action="store_true", help="lowercase the whole name")
+    r.add_argument("--sort", choices=["name", "date", "taken", "size"], default="name", help="order used for {n}")
+    r.add_argument("--start", type=int, default=1, help="first value of {n} (default: 1)")
+
+    u = sub.add_parser("undo", help="revert the last applied run in a folder")
+    u.add_argument("folder", type=Path)
+    u.add_argument("--journal", type=Path, help="a specific journal file to revert")
+
+    for name, what in (("organize", "sort files into folders"), ("dedupe", "move exact duplicates aside")):
+        pro = sub.add_parser(name, help=f"[Pro] {what}")
+        pro.add_argument("rest", nargs=argparse.REMAINDER, help=argparse.SUPPRESS)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Windows consoles/redirects may use a legacy code page: never crash on a file name.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="replace")
+    args = build_parser().parse_args(argv)
+    if args.command in ("organize", "dedupe"):
+        # Non-zero so a script calling it never mistakes "not available" for success.
+        print(f"`{args.command}` is part of TidyBatch Pro (one-time purchase, includes ready-to-run apps):\n"
+              f"  https://whop.com/tidybatch/bulk-file-renamer/\n"
+              "TidyBatch Core (this version) does `rename` and `undo`.", file=sys.stderr)
+        return 2
+    root: Path = args.folder.expanduser()
+    if not root.is_dir():
+        print(f"error: '{root}' is not a folder", file=sys.stderr)
+        return 2
+
+    try:
+        if args.command == "undo":
+            return undo(root, args.journal)
+
+        files = sort_files(iter_files(root, args.recursive, args.glob, args.hidden),
+                           getattr(args, "sort", "name"))
+        moves = plan_rename(files, args.template, args.find,
+                            args.replace, args.slug, args.lower, args.start)
+
+        show_plan(moves, root, applying=args.apply)
+        if not moves:
+            return 0
+        if not args.apply:
+            print("Dry run: nothing was changed. Add --apply to do it.")
+            return 0
+        journal = apply_moves(moves, root)
+        print(f"Done. To revert: tidybatch undo \"{root}\"   (journal: {journal.name})")
+        return 0
+    except TidyError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print("\nInterrupted. Files already moved are listed in the journal; run `undo` to revert.", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())