panda-filesorter 0.3.0

Sort files by extension or category from the command line

███████╗ ██████╗ ██████╗ ████████╗███████╗██████╗
██╔════╝██╔═══██╗██╔══██╗╚══██╔══╝██╔════╝██╔══██╗
█████╗  ██║   ██║██████╔╝   ██║   █████╗  ██████╔╝
██╔══╝  ██║   ██║██╔══██╗   ██║   ██╔══╝  ██╔══██╗
██║     ╚██████╔╝██║  ██║   ██║   ███████╗██║  ██║
╚═╝      ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝

Organise your Chaos : a CLI tool to sort files by extension or category (list of extensions in by genre), with recursive mode, the choice between copy/move, and a way to run in the background that watches folders in real time and auto-sorts according to the user's needs.

Requirements :

Python 3.7 + (with pip)
macOS / Linux (Windows not supported due to daemon mode)

Installation :

From my github repo :

Run these commands :

    git clone https://github.com/yourusername/filesorter.git
    cd filesorter
    pip install -e .

Or directly with pip :

    pip install panda-filesorter

Usage :

FORMAT :
    filesorter <command> [arguments]

COMMANDS :

    sort <path/to/directory/that/needs/sorting> <category/filetype> <path/to/destinationDirectory> - single-time sorting (if destinationDirectory does not exist it will be created)
    watch <path/to/directory/that/needs/sorting> <category/filetype> <path/to/destinationDirectory> - continuously watch a directory and sort new files
    stop <path/to/watchedDirectory> - stop a background watcher

    HINT : use a command with only the -h flag to get help :

FLAGS :

    --recursive, -r       : Process subfolders (sort command only)
    --copy                : Copy files instead of moving (default is move)
    --background, -bg     : Run watch as background daemon (So you dont need to keep it running)
    --type EXT, -t        : Sort by a single extension (e.g. .png)
    --category CAT, -c    : Sort by predefined category (see table below)


EXAMPLES :
    filesorter sort --help      -> Gets help and format for sort command
    filesorter sort ~/Desktop ~/Documents --type .pdf --copy -> Takes all pdfs in the Desktop folder and copies them to the Documents folder
    filesorter watch ~/Desktop ~/Screenshots --category img --background -> Continuously moves all image files in the Desktop folder into the Screenshots folder in the background

CATEGORIES :
    img : .jpg, .jpeg, .png, .gif, .bmp, .tiff, .webp, .svg, .ico
    doc : .pdf, .docx, .doc, .txt, .md, .rtf, .odt, .tex
    video : .mp4, .mov, .avi, .mkv, .flv, .wmv, .webm
    audio : .mp3, .wav, .flac, .aac, .ogg, .m4a
    archive : .zip, .tar, .gz, .rar, .7z, .bz2, .xz
    code : .py, .js, .html, .css, .cpp, .c, .java, .go, .rs, .php, .rb, .swift, .kt
    spreadsheet : .xlsx, .xls, .csv, .ods
    presentation : .pptx, .ppt, .key, .odp
    executable : .exe, .msi, .app, .deb, .rpm, .sh, .bat
    diskimage : .iso, .img, .dmg
    font : .ttf, .otf, .woff, .woff2
    ebook : .epub, .mobi, .azw, .fb2
    cad : .dwg, .dxf, .stl, .obj
    database : .db, .sqlite, .sql, .mdb
    config : .json, .yaml, .yml, .xml, .toml, .ini, .cfg

Command not found after install?

If you run filesorter and get command not found, the Python scripts directory is not in your PATH.

Fix (macOS / Linux):

1. Find where Python installs scripts:

   python3 -m site --user-base
   Then add /bin to that path (e.g., /Users/you/Library/Python/3.10/bin)
   

Add this line to your ~/.zshrc or ~/.bashrc:

export PATH="$PATH:/path/to/python/bin"

Reload your shell:

source ~/.zshrc

Or use the module directly:

python3 -m filesorter --help

This Project was created from scratch for the Stardance coding event by Hack Club inc.

Specific flags for commands (again)

filesorter sort <source_dir> <dest_dir> [flags]

Flags specific to sort:

• --type EXT, -t – sort by a single extension (e.g. .pdf)
• --category CAT, -c – sort by a predefined category
• --recursive, -r – process subfolders
• --copy – copy instead of move (default is move)

watch – continuous monitoring

Flags specific to watch:

• --type EXT, -t – watch for a single extension
• --category CAT, -c – watch for a category
• --copy – copy instead of move
• --background, -bg, -b – run as a background daemon

stop – stop a background watcher

Summary table

Flag	sort	watch	stop
--type, -t	✅	✅	❌
--category, -c	✅	✅	❌
--recursive, -r	✅	❌	❌
--copy	✅	✅	❌
--background, -bg, -b	❌	✅	❌