Skip to content

README.md

Latest commit

 

History

History
262 lines (201 loc) · 6.4 KB

README.md

File metadata and controls

262 lines (201 loc) · 6.4 KB
Raw

Smart File Organizer

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

Java License Platform

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.