warpclean 0.1.1

WARPCLEAN - Blazing Fast Python CLI File Organizer

⚡ WARPCLEAN

WARPCLEAN is a blazing fast, deterministic, and content-aware CLI file organizer. It uses multi-threading and smart heuristics to transform cluttered directories into structured workspaces in seconds.

---

✨ Features

• 🚀 Blazing Fast: Uses ThreadPoolExecutor for concurrent I/O and os.scandir for rapid directory traversal.
• 🧠 Content-Aware: Identifies files by magic bytes (signatures), not just extensions (via python-magic).
• 🛡️ Safety First: * Dry Run: Preview exactly what will happen before moving a single byte.
  • Undo System: Revert the last $N$ batches of operations with a single command.
  • Collision Resolution: Automatically renames files (e.g., image_1.jpg) to prevent data loss.
• 📂 Smart Grouping: Automatically detects file sequences and fuzzy matches to keep related projects together.
• 📅 Date-Based Org: Optional organization into YYYY/MM/DD folder structures.
• 🔍 Duplicate Detection: MD5-based hashing to skip redundant files.

---

🛠️ Installation

If you've followed the package conversion steps, you can install it via:

# From the project root
pip install .

Dependencies:

• rich (for beautiful UI and progress bars)
• python-magic (for file type identification)
• orjson (optional, for high-speed log processing)

---

🚀 Usage

Basic Command

warpclean /path/to/your/cluttered/folder

Power User Examples

Goal	Command
Safe Preview	warpclean ./downloads --dry-run --tree
Photo Backup	warpclean ./photos --date-based --copy --detect-duplicates
Massive Clean	warpclean ./files --fast --progress --clean-empty-dirs
Undo Last Move	warpclean ./files --undo 1

---

📋 Categorization Logic

WARPCLEAN sorts files into the following standard hierarchy:

• Pictures: .jpg, .png, .raw, ...
• Videos: .mp4, .mkv, .mov, ...
• Audio: .mp3, .wav, .flac, ...
• Documents: .pdf, .docx, .txt, .md, ...
• Installers: .exe, .msi, .sh, .dmg, ...
• Archives: .zip, .tar.gz, .7z, ...
• Collections: Grouped by sequence or project name.

---

🛠️ Advanced Options

• --group-related: Groups sequences like IMG_001, IMG_002 into a dedicated folder.
• --fast: Skips deep content analysis and trusts extensions (ideal for huge NAS drives).
• --copy: Leaves originals untouched and creates an organized copy in a warpclean/ subfolder.
• --tree: Visualizes the new structure in a tree format during dry runs.

---

🤝 Contributing

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

Developed by Srimoneyshankar Ajith