file-organizer

Automatically sort your chaotic directories into clean, categorized folders — in one command.

 Scanning /Users/you/Downloads…

 DRY RUN  14 files to organize:

    images/  (5 files)
    → photo_vacation.jpg
    → screenshot_2024.png
    → logo.svg

   documents/  (4 files)
    → resume.pdf
    → notes.md
    → report.docx

   audio/  (2 files)
    → podcast_ep42.mp3
    → lo-fi-beats.flac

   code/  (3 files)
    → main.rs
    → config.toml
    → deploy.sh

   Run without --dry-run to apply these changes.

---

Features

• One-command organization — walks a directory and sorts files by extension
• 7 categories — images, documents, videos, audio, archives, code, other
• Dry-run preview — see exactly what would happen before committing
• Verbose mode — file-by-file logging of every move
• Safe & atomic — skips directories, handles permission errors gracefully, never overwrites
• Cross-device moves — falls back to copy+delete when rename fails across filesystems
• Colored output — green for images, blue for docs, orange for code, etc.

---

Installation

Prerequisites

• Rust toolchain (stable, 1.70+)

Build from source

git clone https://github.com/you/file-organizer
cd file-organizer
cargo build --release

The binary lands at target/release/file-organizer.

Install globally

cargo install --path .

---

Usage

Usage: file-organizer [OPTIONS] <PATH>

Arguments:
  <PATH>  Directory to organize

Options:
  -n, --dry-run  Preview what would be moved without making any changes
  -v, --verbose  Print each file operation as it happens
  -h, --help     Print help
  -V, --version  Print version

Examples

# Preview what will happen (safe — no files moved)
file-organizer ~/Downloads --dry-run

# Organize your Downloads folder
file-organizer ~/Downloads

# Organize with verbose file-by-file logging
file-organizer ~/Downloads --verbose

# Organize a project directory
file-organizer /tmp/messy-project --dry-run

---

Extension Groups

Category	Extensions
images/	jpg, jpeg, png, gif, webp, svg, bmp, ico, tiff, raw, heic
documents/	pdf, doc, docx, txt, md, rtf, odt, xls, xlsx, csv, ppt, pptx
videos/	mp4, avi, mkv, mov, webm, flv, wmv, m4v, mpeg
audio/	mp3, wav, flac, aac, ogg, m4a, wma, opus
archives/	zip, rar, tar, gz, 7z, bz2, xz, tgz, zst
code/	rs, py, js, ts, java, cpp, c, h, go, rb, php, swift, kt, cs, sh, sql, html, css, json, yaml, toml …
other/	everything else

---

Safe Behavior

• Never overwrites — if a destination file already exists, it's skipped and logged
• Skips hidden files — dotfiles (.DS_Store, .gitignore, etc.) are ignored
• Skips subdirectories — only processes immediate children of the target path
• Permission errors — reported as warnings, never crash the whole run
• Cross-device atomicity — if rename(2) fails (e.g., moving across mount points), falls back to copy + delete

---

Demo Commands (for GIF recording)

# 1. Set up a messy test dir
mkdir /tmp/demo
touch /tmp/demo/{photo.jpg,screenshot.png,resume.pdf,notes.md,main.rs,music.mp3,archive.zip}

# 2. Dry-run preview
file-organizer /tmp/demo --dry-run

# 3. Actual organize (verbose)
file-organizer /tmp/demo --verbose

# 4. Confirm results
ls /tmp/demo/images/ /tmp/demo/documents/ /tmp/demo/code/

---

Project Structure

file-organizer/
├── Cargo.toml
└── src/
    └── main.rs        # ~480 LOC, zero external scripts

Dependencies

Crate	Purpose
clap 4	CLI argument parsing with derive macros
walkdir	Portable, ergonomic directory traversal
anyhow	Flexible, context-rich error handling
colored	Cross-platform ANSI terminal colors

---

License

MIT