warpclean 0.1.2

WARPCLEAN - Blazing Fast Python CLI File Organizer

WARPCLEAN

WARPCLEAN is a deterministic, rule-based Python CLI package for organizing files at warp speed — safely, predictably, and reversibly.

Install it once, run it anywhere, and clean up directories without fear of losing files or ending up with a structure you didn’t agree to.

---

Installation

WARPCLEAN is distributed as a Python package.

pip install warpclean

Once installed, the warpclean command is available globally:

warpclean --help

Requirements

• Python 3.9 or newer
• No mandatory dependencies

Optional (but recommended):

• rich – colored output, tables, progress bars
• python-magic – deeper MIME detection

---

Quick Start

Safely preview what will happen

warpclean ~/Downloads --dry-run

Nothing is moved. You get a full simulation.

---

Organize files for real

warpclean ~/Downloads

Files are moved into structured category folders.

---

Organize without touching originals

warpclean ~/Downloads --copy

Creates an organized warpclean/ subdirectory and leaves originals untouched.

---

What WARPCLEAN Does (At a High Level)

WARPCLEAN runs a strict, predictable pipeline:

1. Scan the target directory recursively
2. Classify each file using MIME types and extensions
3. Optionally detect duplicates
4. Optionally group related files
5. Plan all file operations
6. Execute moves or copies
7. Log operations for undo

No step mutates the filesystem until the plan is complete.

---

Default Organization Rules

By default, files are organized into:

• Pictures/
• Videos/
• Audio/
• Documents/
• Archives/
• Installers/
• Misc/

Classification is based on:

• MIME type (preferred)
• File extension fallback
• Explicit category rules

No guessing, no machine learning, no heuristics that change over time.

---

Warp-Speed Mode

warpclean ~/Downloads --fast

Warp-speed mode skips expensive content inspection and trusts file extensions.

Use this when:

• Organizing very large directories
• You trust extensions
• Throughput matters more than deep inspection

Avoid this mode when:

• Extensions are unreliable
• Precision matters more than speed

---

Dry Run (Simulation Mode)

warpclean ~/Downloads --dry-run

Dry run mode:

• Executes the full pipeline
• Builds a complete move plan
• Shows exactly what would happen
• Touches zero files

This is the recommended way to run WARPCLEAN for the first time.

---

Tree View (Dry Run Only)

warpclean ~/Photos --dry-run --tree

Displays the planned result as a directory tree instead of a table.

Useful for visualizing large reorganizations before committing.

---

Copy Mode

warpclean ~/Downloads --copy

Instead of moving files, WARPCLEAN:

• Creates a warpclean/ subdirectory
• Recreates the organized structure inside it
• Copies files into the new structure

Original files remain untouched.

---

Date-Based Organization

warpclean ~/Photos --date-based

Images and videos are organized by modification date:

Pictures/YYYY/MM/DD/
Videos/YYYY/MM/DD/

Ideal for:

• Camera dumps
• Screenshots
• Media archives

---

Grouping Related Files

warpclean ~/Projects --group-related

WARPCLEAN can group related files together, including:

• Numbered sequences (img_001.jpg, img_002.jpg)
• Versioned documents (report_v1.docx, report_final.docx)
• Sidecar files sharing the same stem

Grouped files are placed into a single collection folder to prevent separation.

---

Duplicate Detection

warpclean ~/Files --detect-duplicates

Duplicate detection uses:

1. File size filtering
2. MD5 hash comparison

Behavior:

• First occurrence is organized
• Subsequent duplicates are skipped
• No files are deleted automatically

---

Undo System

Every successful operation is logged automatically.

Log file:

.warpclean_undo.jsonl

Undo the last operation batch

warpclean ~/Downloads --undo

Undo multiple batches

warpclean ~/Downloads --undo 3

Undo everything

warpclean ~/Downloads --undo 0

Undo restores files to their original locations and cleans up empty directories when possible.

---

Cleaning Empty Directories

warpclean ~/Downloads --clean-empty-dirs

Recursively removes empty directories after organization or undo.

Safe to use with dry-run for previewing.

---

Command-Line Options

warpclean <path> [options]

Common options:

• --dry-run Simulate operations without moving files
• --fast Enable warp-speed mode
• --copy Copy instead of move
• --group-related Group related files together
• --detect-duplicates Skip duplicate files
• --date-based Organize images/videos by date
• --tree Tree view output (dry-run only)
• --progress Show progress bars (requires rich)
• --undo [N] Undo last N batches (0 = all)
• --clean-empty-dirs Remove empty directories
• --verbose Enable debug logging
• --color Enable colored output

---

Safety Guarantees

WARPCLEAN guarantees that it will:

• Never overwrite existing files
• Never delete files automatically
• Resolve name collisions safely (file_1.txt, file_2.txt)
• Skip files already in the correct location
• Always allow a dry-run preview
• Always allow undo of completed operations

---

Who This Package Is For

WARPCLEAN is built for:

• Developers
• Power users
• Students managing large project folders
• Anyone who wants predictable file organization

If you want control, reversibility, and warp-speed execution, this tool is designed for you.

---

License

MIT License

---

Final Advice

Run a dry run first.
Warp speed is powerful — control keeps it safe.