# ⚡ 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:

```bash
# 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

```bash
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** 


