warpclean 0.1.4
WARPCLEAN - A CLI tool to organize your files at Warp Speed
Requires Python: >=3.8

# WARPCLEAN

## Organize Your Files at Warp Speed

```bash
pip install warpclean
```

WARPCLEAN is a deterministic, rule-based Python CLI for organizing files. It is built for speed, safety, and reversibility. No machine learning. No unpredictable heuristics. Just a fast, reliable pipeline that does exactly what you expect.

Point it at any directory. Preview what will happen. Execute when ready. Undo if needed.

---

## The Problem

Your Downloads folder is a disaster. Your Desktop is cluttered. Your photo library is a mess of `IMG_0001.jpg` duplicates scattered across five folders.

You need to organize, but:

- You don't want to lose files
- You don't want to spend hours doing it manually
- You don't trust tools that move things without showing you first
- You need a way to undo if something goes wrong

---

## The Solution

WARPCLEAN gives you complete control:

| Feature                   | What It Does                                            |
| ------------------------- | ------------------------------------------------------- |
| **Dry Run**               | See exactly what will happen before any file is touched |
| **Undo System**           | Every operation is logged and fully reversible          |
| **Copy Mode**             | Organize into a new folder without moving originals     |
| **Warp Drive Mode**       | Skip deep content analysis for maximum speed            |
| **Duplicate Detection**   | Identify and skip duplicate files automatically         |
| **Date Organization**     | Sort photos and videos by year, month, and day          |
| **Related File Grouping** | Keep sequences and versions together                    |
| **Progress Tracking**     | Visual progress bars for large operations               |

---

## Installation

**Requirements:** Python 3.9 or newer

```bash
pip install warpclean
```

Once installed, the `warpclean` command is available globally in your terminal.

### Optional Dependencies

| Package        | Purpose                                                      |
| -------------- | ------------------------------------------------------------ |
| `rich`         | Colored terminal output, formatted tables, and progress bars |
| `python-magic` | Deep MIME-type detection using file content signatures       |

Install them with:

```bash
pip install rich python-magic
```

---

## Quick Start

### Preview Before You Organize

Run a dry run to see what WARPCLEAN would do without touching any files:

```bash
warpclean ~/Downloads --dry-run
```

This executes the full classification and planning pipeline, then displays a complete report of all proposed moves. Nothing is changed on disk.

### Organize For Real

When you are ready:

```bash
warpclean ~/Downloads
```

Files are moved into structured category folders. Every operation is logged for undo.

### Keep Your Originals

If you want to organize without moving the source files:

```bash
warpclean ~/Downloads --copy
```

This creates a `warpclean/` subdirectory containing the organized structure. Your original files remain exactly where they were.

---

## How It Works

WARPCLEAN runs a strict five-stage pipeline:

```
SCAN  >>>  CLASSIFY  >>>  PLAN  >>>  EXECUTE  >>>  LOG
```

### Stage 1: Scan

Recursively discovers all files in the target directory. Hidden files and system files are respected. Symbolic links are handled safely.

### Stage 2: Classify

Each file is analyzed to determine its type. Classification uses:

1. **MIME type detection** (preferred, uses file content signatures)
2. **File extension** (fallback when MIME detection is unavailable)
3. **Explicit category rules** (for special file types like installers)

In Warp Drive Mode (`--fast`), content analysis is skipped and extensions are trusted directly.

### Stage 3: Plan

A complete operation plan is built before any changes occur. The plan includes:

- Source and destination paths for every file
- Collision resolution (automatic renaming if destination exists)
- Skip decisions for files already in correct locations

### Stage 4: Execute

Moves or copies are performed atomically. If any operation fails, the pipeline stops cleanly.

### Stage 5: Log

Every successful operation is recorded to `.warpclean_undo.jsonl` in the target directory. This log enables full reversal of any batch of operations.

---

## Organization Categories

Files are sorted into these default categories:

| Category      | File Types                                        |
| ------------- | ------------------------------------------------- |
| `Pictures/`   | JPEG, PNG, GIF, WebP, SVG, RAW formats, PSD, HEIC |
| `Videos/`     | MP4, MKV, AVI, MOV, WebM, FLV, WMV                |
| `Audio/`      | MP3, FLAC, WAV, AAC, OGG, M4A, AIFF               |
| `Documents/`  | PDF, DOCX, XLSX, PPTX, TXT, MD, ODT, EPUB         |
| `Archives/`   | ZIP, RAR, 7Z, TAR, GZ, BZ2, XZ                    |
| `Installers/` | EXE, MSI, DMG, DEB, RPM, AppImage                 |
| `Misc/`       | Everything else                                   |

Classification is deterministic. The same file will always be placed in the same category.

---

## Feature Reference

### Dry Run Mode

```bash
warpclean ~/Downloads --dry-run
```

Simulates the entire organization process without modifying any files. Displays a detailed table showing:

- Original file path
- Planned destination
- Classification reason
- Any warnings or skip decisions

This is the recommended first step for any new directory.

### Tree View

```bash
warpclean ~/Downloads --dry-run --tree
```

Displays dry run results as a visual directory tree instead of a table. Useful for understanding the final folder structure before committing.

### Copy Mode

```bash
warpclean ~/Downloads --copy
```

Instead of moving files, creates organized copies in a `warpclean/` subdirectory:

```
~/Downloads/
├── original_file.pdf           # untouched
├── another_file.jpg            # untouched
└── warpclean/
    ├── Documents/
    │   └── original_file.pdf   # organized copy
    └── Pictures/
        └── another_file.jpg    # organized copy
```

Perfect for organizing without risk, or for creating a parallel organized structure.

### Warp Drive Mode

```bash
warpclean ~/Downloads --fast
```

Skips content-based MIME detection and trusts file extensions directly. This dramatically increases throughput for large directories.

**Use when:**

- Processing thousands of files
- Extensions are reliable
- Speed is more important than deep content inspection

**Avoid when:**

- Files have incorrect or missing extensions
- You need precise content-based classification

### Date-Based Organization

```bash
warpclean ~/Photos --date-based
```

Organizes images and videos into a date-based folder hierarchy:

```
Pictures/
└── 2024/
    └── 01/
        └── 15/
            ├── IMG_0001.jpg
            └── IMG_0002.jpg
```

Uses file modification time to determine dates. Ideal for camera dumps, screenshots, and media archives.

### Duplicate Detection

```bash
warpclean ~/Files --detect-duplicates
```

Detects duplicate files using a two-stage process:

1. **Size filtering:** Files with unique sizes are immediately cleared
2. **MD5 hashing:** Files with matching sizes are hashed and compared

Behavior:

- First occurrence is organized normally
- Subsequent duplicates are skipped
- No files are deleted automatically
- Duplicate count is reported at the end

### Related File Grouping

```bash
warpclean ~/Projects --group-related
```

Identifies and groups files that belong together:

| Pattern            | Example                                                 |
| ------------------ | ------------------------------------------------------- |
| Numbered sequences | `img_001.jpg`, `img_002.jpg`, `img_003.jpg`             |
| Versioned files    | `report_v1.docx`, `report_v2.docx`, `report_final.docx` |
| Sidecar files      | `photo.jpg`, `photo.xmp`, `photo.jpg.json`              |

Grouped files are placed together in a collection folder to prevent separation.

### Progress Bars

```bash
warpclean ~/Downloads --progress
```

Displays visual progress bars during scanning, classification, and execution. Requires the `rich` library.

Shows:

- Current operation
- Files processed / total files
- Elapsed time
- Estimated time remaining

### Depth Control

```bash
warpclean ~/Downloads --depth 0
```

Limits how deep WARPCLEAN scans into subdirectories:

| Value       | Behavior                                      |
| ----------- | --------------------------------------------- |
| `--depth 0` | Only files in the root directory (no subdirs) |
| `--depth 1` | Root + immediate subdirectories               |
| `--depth 2` | Up to 2 levels deep                           |
| (default)   | Unlimited depth (scan everything)             |

**Use when:**

- You only want to organize files at the top level
- You want to avoid touching deeply nested project folders
- You need fine control over which directories are processed

Example: Organize only files directly in Downloads, ignoring subfolders:

```bash
warpclean ~/Downloads --depth 0 --dry-run
```

### Colored Output

```bash
warpclean ~/Downloads --color
```

Enables rich colored output with formatted tables and syntax highlighting. Requires the `rich` library.

### Verbose Logging

```bash
warpclean ~/Downloads --verbose
```

Enables detailed debug output. Shows:

- Every file discovered during scan
- Classification decisions and reasoning
- Plan generation details
- Individual operation results

### Empty Directory Cleanup

```bash
warpclean ~/Downloads --clean-empty-dirs
```

After organization (or undo), recursively removes any empty directories left behind. Only removes directories that are completely empty.

---

## Undo System

Every operation batch is logged to `.warpclean_undo.jsonl` in the target directory.

### Undo Last Operation

```bash
warpclean ~/Downloads --undo
```

Reverses the most recent batch of operations. Files are moved back to their original locations.

### Undo Multiple Batches

```bash
warpclean ~/Downloads --undo 3
```

Reverses the last 3 batches of operations.

### Undo Everything

```bash
warpclean ~/Downloads --undo 0
```

Reverses all logged operations. Returns the directory to its original state.

### How Undo Works

- Operations are replayed in reverse order
- Destination directories created during organization are cleaned up
- The undo itself is not logged (prevents infinite loops)
- If a file has been modified or deleted since organization, undo will skip it safely

---

## Command Reference

```bash
warpclean <path> [options]
```

### Positional Arguments

| Argument | Description                  |
| -------- | ---------------------------- |
| `path`   | Target directory to organize |

### Options

| Flag                  | Description                                                 |
| --------------------- | ----------------------------------------------------------- |
| `--dry-run`           | Simulate operations without moving files                    |
| `--fast`              | Warp drive mode: trust extensions, skip content detection   |
| `--copy`              | Copy files to `warpclean/` subdirectory instead of moving   |
| `--date-based`        | Organize images and videos by date (YYYY/MM/DD structure)   |
| `--detect-duplicates` | Identify and skip duplicate files                           |
| `--group-related`     | Keep related files (sequences, versions, sidecars) together |
| `--tree`              | Display dry run results as a directory tree                 |
| `--undo [N]`          | Undo last N operation batches (default: 1, use 0 for all)   |
| `--clean-empty-dirs`  | Remove empty directories after organizing                   |
| `--progress`          | Show progress bars during operations                        |
| `--color`             | Enable colored terminal output                              |
| `--verbose`, `-v`     | Enable detailed debug logging                               |
| `--help`, `-h`        | Show help message                                           |

---

## Safety Guarantees

WARPCLEAN is built with safety as a core design principle:

| Guarantee              | Description                                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **No overwrites**      | Destination files are never overwritten. Name collisions are resolved automatically (`file.txt` becomes `file_1.txt`). |
| **No deletions**       | Files are never deleted. Duplicates are skipped, not removed.                                                          |
| **No surprises**       | Dry run shows exactly what will happen. The filesystem is unchanged until you confirm.                                 |
| **Full reversibility** | Every operation is logged. Undo restores files to their exact original locations.                                      |
| **Clean failures**     | If an operation fails, the pipeline stops. Partial results are logged and can be undone.                               |

---

## Real-World Examples

### Clean Up a Downloads Folder

```bash
warpclean ~/Downloads --progress --clean-empty-dirs
```

Organizes all files into categories, shows progress, and removes empty folders afterward.

### Organize Years of Photos

```bash
warpclean ~/Photos --date-based --copy --detect-duplicates --progress
```

Creates a date-organized copy of your photo library, skipping duplicates and showing progress.

### Preview a Project Folder

```bash
warpclean ~/Projects --dry-run --tree --group-related
```

Shows what organization would look like, with related files grouped and displayed as a tree.

### Full-Featured Organization

```bash
warpclean ~/Messy --copy --date-based --detect-duplicates --group-related --progress --color
```

Uses every major feature: copies instead of moves, organizes by date, detects duplicates, groups related files, and shows colorful progress output.

### Undo After Testing

```bash
warpclean ~/Downloads --undo 0
```

Reverses all operations and returns the directory to its original state.

---

## License

MIT License

---

## One Last Thing

Always run a dry run first.

```bash
warpclean ~/YourFolder --dry-run
```

Warp speed is powerful. Control keeps it safe.