# 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.
