tidyup
A small, safe file organizer: sort a messy folder by type or date, with one-command undo. Repo ↗
A small, safe file organizer for folders that have gotten out of hand.
tidyup sorts files into subfolders by type, previews every move before
touching anything, never overwrites a file it did not create, and can undo an
entire run with one command.
Install
$ pipx install git+https://github.com/pdev-labs/tidyup
Or from a checkout:
$ pip install -e ".[dev]"
Usage
$ tidyup ~/Downloads --dry-run
Would move 3 file(s) in /home/you/Downloads
invoice.pdf -> Documents/invoice.pdf
shot.png -> Images/shot.png
call.mp3 -> Audio/call.mp3
Then drop --dry-run to do it for real.
$ tidyup ~/Downloads --by date # 2026/10/ instead of category folders
$ tidyup ~/Downloads --by extension # one folder per suffix, e.g. png/
$ tidyup ~/Downloads -r # include subfolders
$ tidyup ~/Downloads -x "*.part" # leave matching files where they are
$ tidyup ~/Downloads --json # machine-readable plan
$ tidyup ~/Downloads --prune-empty # remove folders the sort emptied
$ tidyup ~/Downloads --on-collision skip # leave clashing files alone
$ tidyup ~/Downloads --min-age 7 # skip anything touched in the last week
$ tidyup ~/Downloads --exclude-from .tidyupignore # globs from a file
Configuration
Drop a .tidyup.toml in the folder to make flags the default:
by = "date"
recursive = true
exclude = ["*.part", "*.crdownload"]
min_age = 3
prune_empty = true
Flags on the command line always win, so a one-off run is never blocked by the file. Unknown keys and invalid values are reported by name instead of being ignored.
In a cron job
--check exits 1 when something would move and 0 when the folder is already
sorted, without touching anything, so a scheduled run can alert instead of act:
$ tidyup ~/Downloads --check --min-age 7 || echo "Downloads needs tidying"
Duplicates
$ tidyup ~/Downloads --duplicates
1.2 MB each, 2 copies:
holiday.mp4
old/holiday-copy.mp4
Total reclaimable: 1.2 MB
Files are bucketed by size first, so only plausible matches are hashed. Use
--duplicates --json for scripting. This mode never moves anything.
Undo
Every real run (never a --dry-run) writes .tidyup/journal/<timestamp>.json
inside the folder it tidied. That makes the last run reversible:
$ tidyup ~/Downloads --undo --dry-run # preview the restore
$ tidyup ~/Downloads --undo # put everything back
Restoring also removes the category folders the run created, if they are now empty, and it renames instead of overwriting if a file with the old name has reappeared in the meantime. Journals store relative paths, so moving the folder does not break them.
Runs are kept, not overwritten, so you can go further back:
$ tidyup ~/Downloads --history
20261029T151113084211Z 2026-10-29T15:11:13+00:00 12 file(s)
20261029T150204771930Z 2026-10-29T15:02:04+00:00 3 file(s)
$ tidyup ~/Downloads --undo-id 20261029T150204
Safety model
--dry-runis the default path in the docs and shows the exact plan first.- Name collisions are resolved by renaming, never by overwriting.
- Every run writes an undo journal, so a mistake is one command away from fixed.
License
MIT
Files
- .github/workflows/ci.yml
- .gitignore
- LICENSE
- README.md
- pyproject.toml
- src/tidyup/__init__.py
- src/tidyup/categories.py
- src/tidyup/cli.py
- src/tidyup/config.py
- src/tidyup/duplicates.py
- src/tidyup/journal.py
- src/tidyup/organizer.py
- tests/test_cli.py
- tests/test_config.py
- tests/test_duplicates.py
- tests/test_journal.py
- tests/test_organizer.py