WARPCLEAN

Organize Your Files at Warp Speed

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
Depth Control	Limit recursion with --depth N
Exclude Patterns	Skip files/dirs via --exclude, --exclude-file, or .warpcleanignore

---

Installation

Requirements: Python 3.8 or newer

pip install warpclean

Once installed, the warpclean command is available globally in your terminal.

Development Setup

To work on WARPCLEAN from source, this project uses uv:

uv venv
uv pip install -e .

Publishing to PyPI

Set a PyPI API token once per shell:

$env:UV_PUBLISH_TOKEN = "pypi-..."

Then:

.\publish.ps1              # build + publish current version
.\publish.ps1 patch        # bump patch version, then build + publish
.\publish.ps1 minor -Test  # bump minor, publish to TestPyPI

Raw uv equivalents:

uv version --bump patch    # 0.1.3 -> 0.1.4
uv build                   # wheel + sdist into dist/
uv publish                 # upload to PyPI
uv publish --index testpypi  # upload to TestPyPI

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:

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:

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:

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:

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 file by file. If an individual operation fails (e.g. a permission error), it is logged with an error status and the pipeline continues with the remaining files rather than aborting.

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

warpclean ~/Downloads --dry-run

Simulates the entire organization process without modifying any files. Displays a detailed table showing:

• Source file name
• Action (move/copy direction)
• Destination path

This is the recommended first step for any new directory.

Tree View

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

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

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

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

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

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

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

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:

warpclean ~/Downloads --depth 0 --dry-run

Exclude Patterns

warpclean ~/Downloads --exclude node_modules --exclude "*.tmp"

Skips files and directories matching gitignore-lite patterns. Patterns come from three sources, merged together:

Source	How
--exclude PATTERN	Repeatable flag, one pattern per use
--exclude-file PATH	A file with one pattern per line
.warpcleanignore	Auto-discovered in the target directory, no flag needed

Pattern syntax (gitignore-lite, no negation / ! support):

Pattern	Behavior
# comment	Ignored, as are blank lines
node_modules	No / — matches this basename anywhere
build/	Trailing / — matches directories only
src/tmp	Contains / — matches against the path relative to the scan root

Example .warpcleanignore:

# build artifacts
node_modules
*.tmp
dist/

Use when:

• You want to skip version control or dependency folders
• You have temp/cache files that shouldn't be organized
• You want a reusable, per-directory ignore file instead of repeating flags

Colored Output

warpclean ~/Downloads --color

Enables rich colored output with formatted tables and syntax highlighting. Requires the rich library.

Verbose Logging

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

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

warpclean ~/Downloads --undo

Reverses the most recent batch of operations. Files are moved back to their original locations.

Undo Multiple Batches

warpclean ~/Downloads --undo 3

Reverses the last 3 batches of operations.

Undo Everything

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

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
--depth N	Limit scan depth (0 = root only; default unlimited)
--exclude PATTERN	Gitignore-style exclude pattern (repeatable, no negation)
--exclude-file PATH	File with one gitignore-style exclude pattern per line
--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, it is logged as an error and the pipeline continues. Completed operations can be undone.

---

Real-World Examples

Clean Up a Downloads Folder

warpclean ~/Downloads --progress --clean-empty-dirs

Organizes all files into categories, shows progress, and removes empty folders afterward.

Organize Years of Photos

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

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

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

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.

warpclean ~/YourFolder --dry-run

Warp speed is powerful. Control keeps it safe.