File Organizer

A small, dependency-free Python CLI that tidies up a messy directory — sort files into folders by type (Images, Documents, Video, Code, ...) or by the date they were last modified. Every run keeps a JSON log so you can undo it.

Why

Downloads folders and desktops accumulate hundreds of unsorted files. This tool sorts them in one command, is safe to run repeatedly (already-organized files are left alone), and never destroys anything — moves are logged and fully reversible.

Features

• Two organization modes: by extension category (Images, Documents, Video, Code, Archives, ...) or by modification date (YYYY/MM)
• Undo support — every run writes a move log; file-organizer undo <log> restores the original layout
• Dry-run mode — preview what would move before touching anything
• Recursive mode — optionally include subdirectories
• Collision-safe — same-named files get a numbered suffix instead of overwriting
• Zero third-party dependencies (standard library only)

Installation

git clone https://github.com/SafraNako/python-file-organizer.git
cd python-file-organizer
pip install -e .

Usage

# Sort ~/Downloads by file type
file-organizer organize ~/Downloads

# Preview first, without moving anything
file-organizer organize ~/Downloads --dry-run

# Sort by modification date instead of type
file-organizer organize ~/Downloads --by date

# Include subdirectories
file-organizer organize ~/Downloads --recursive

# Undo the last run
file-organizer undo ~/Downloads/.file-organizer-log.json

Example

$ file-organizer organize ~/Downloads --dry-run
would move: /Users/me/Downloads/invoice.pdf -> /Users/me/Downloads/Documents/invoice.pdf
would move: /Users/me/Downloads/vacation.jpg -> /Users/me/Downloads/Images/vacation.jpg
would move: /Users/me/Downloads/song.mp3 -> /Users/me/Downloads/Audio/song.mp3

Development

pip install -e ".[dev]"
pytest -v

License

MIT — see LICENSE.