Smart File Organizer

A clean, fast Java CLI & GUI tool that organizes your messy folders automatically.

---

Tired of a cluttered Downloads folder? Just point this tool at any directory and watch it sort files into neat category folders.

---

Features

• Automatic categorization -- files are sorted by extension into labeled folders
• GUI interface -- graphical desktop app for easy use
• Dry-run mode -- preview what will happen before moving anything
• Recursive mode -- scan and organize subdirectories too
• Watch mode -- real-time file sorting as new files arrive
• Undo -- reverse the last organization in one click
• History -- view all past organization sessions
• Custom categories -- define your own categories via JSON config
• Multi-threaded -- uses all CPU cores for fast organization
• Duplicate handling -- safe renaming (photo.jpg becomes photo_1.jpg)
• Zero external dependencies -- uses only Java standard library

---

Getting Started

Prerequisites

Tool	Version
Java	17 or higher
Maven	3.6+

Build

git clone https://github.com/aydocs/SmartFileOrganizer.git
cd SmartFileOrganizer
mvn clean package

The executable JAR will be at target/smart-file-organizer-2.0.0.jar.

---

Usage

Organize a directory

java -jar target/smart-file-organizer-2.0.0.jar ~/Downloads

Preview first (dry-run)

java -jar target/smart-file-organizer-2.0.0.jar ~/Downloads --dry-run

Recursive (scan subfolders)

java -jar target/smart-file-organizer-2.0.0.jar ~/Downloads -r

Watch mode (real-time sorting)

java -jar target/smart-file-organizer-2.0.0.jar ~/Downloads --watch

Custom categories

java -jar target/smart-file-organizer-2.0.0.jar ~/Downloads --config categories.json

Undo last organization

java -jar target/smart-file-organizer-2.0.0.jar ~/Downloads --undo

View history

java -jar target/smart-file-organizer-2.0.0.jar ~/Downloads --history

Launch GUI

java -jar target/smart-file-organizer-2.0.0.jar --gui

Example Output

Smart File Organizer
--------------------
Directory: /home/user/Downloads
Recursive: No

photo.jpg       -> Images
document.pdf    -> Documents
song.mp3        -> Audio
movie.mp4       -> Videos
archive.zip     -> Archives
Main.java       -> Code
mockup.psd      -> Design
font.ttf        -> Fonts
model.fbx       -> 3D
unknown.xyz     -> Others

--------------------
Files processed: 10
Files moved: 10
Files skipped: 0
Errors: 0

---

Supported File Types

Category	Extensions
Images	.jpg .jpeg .png .gif .webp .svg .bmp .ico .tiff
Documents	.pdf .doc .docx .txt .xls .xlsx .ppt .pptx .csv .rtf .odt
Audio	.mp3 .wav .flac .ogg .aac .wma .m4a
Videos	.mp4 .mkv .avi .mov .webm .flv .wmv .m4v
Archives	.zip .rar .7z .tar .gz .bz2 .xz .zst
Code	.java .py .js .ts .cpp .c .h .cs .go .rs .html .css .php .rb .swift .kt
Design	.psd .ai .sketch .fig .xd
Fonts	.ttf .otf .woff .woff2
3D	.obj .fbx .stl .blend
Others	Everything else, including files without extensions

Custom Categories

Create a categories.json file:

{
  "categories": {
    "Images": ["jpg", "png", "gif"],
    "MyCategory": ["xyz", "abc"]
  }
}

Then run:

java -jar smart-file-organizer.jar ~/Downloads --config categories.json

---

CLI Options

Option	Description
<directory>	Directory to organize
--dry-run	Preview only, do not move files
--recursive, -r	Scan subdirectories recursively
--gui	Launch graphical interface
--watch, -w	Watch mode for real-time sorting
--undo	Undo the last organization
--history	Show past organization sessions
--config, -c	Use a custom JSON config file

---

Project Structure

smart-file-organizer/
├── src/main/java/organizer/
│   ├── Main.java              -- Entry point & CLI parsing
│   ├── FileOrganizer.java     -- Core logic, scanning & multi-threaded moving
│   ├── FileClassifier.java    -- Extension-to-category mapping
│   ├── CategoryConfig.java    -- Custom JSON config loader
│   ├── HistoryManager.java    -- Undo & session history
│   ├── WatchMode.java         -- Real-time file monitoring
│   └── OrganizerGUI.java      -- Swing GUI interface
├── src/test/java/organizer/
│   └── FileClassifierTest.java -- Unit tests
├── categories.json             -- Sample config file
├── pom.xml
└── README.md

Class Overview

Class	Purpose
Main	Parses CLI arguments, validates input, dispatches to features
FileOrganizer	Scans directory, moves files with multi-threading, tracks stats
FileClassifier	Looks up a file's extension and returns its category
CategoryConfig	Loads and parses custom JSON category definitions
HistoryManager	Saves move history, supports undo and history listing
WatchMode	Watches directory for new files and sorts them automatically
OrganizerGUI	Desktop GUI with file browser, options, and live output

---

How It Works

User runs CLI
      |
      v
   Main.java
   validates path
      |
      v
  CategoryConfig
  loads categories
      |
      v
  FileOrganizer
  scans directory (recursive or flat)
      |
      +---> skip if it's a directory (unless recursive)
      |
      v
  FileClassifier
  checks extension via config
      |
      v
  category folder
  created if needed
      |
      v
  file moved (multi-threaded)
  (with duplicate handling)
      |
      v
  HistoryManager
  saves session for undo

---

Testing

mvn test

Runs 13 unit tests verifying correct classification for all categories.