Automatic File Organizer Pro

A high-performance, robust, and feature-rich CLI Python application that automatically categorizes, sorts, and declutters messy directories into structured folder hierarchies—complete with Dry-Run previews, one-click Undo/Rollback capabilities, and real-time storage statistics.

---

Table of Contents

• Overview
• Key Features
• Screenshots & Visual Showcase
• Project Architecture
• Tech Stack
• Installation & Setup
• Usage Guide
• Configuration & Customization
• Logging & History Tracking
• Contributing
• License
• Author & Contact

---

Overview

Cluttered directories filled with mixed images, documents, installation files, and code scripts reduce productivity and consume unnecessary storage space. Automatic File Organizer Pro solves this by scanning targeted directories and instantly grouping files by extension into neatly organized category folders.

Designed with safety and user transparency in mind, it features a Dry-Run (Simulation) Mode to inspect changes before execution, a full Undo / Rollback Engine to restore files back to their exact original locations, and Collision Protection to prevent accidental overwrites.

---

Key Features

• Multi-Category File Sorting: Intelligently categorizes files into standard folders: Images, Documents, Videos, Music, Archives, Code, Programs, Spreadsheets, Ebooks, and more.
• Dry-Run (Preview) Mode: Inspect organization destinations and preview operations safely before moving any physical files.
• Full Undo & Rollback: Revert the previous file movement operation, move files back to original positions, and automatically prune empty category directories created by the tool.
• Comprehensive Folder Statistics: View category file distribution, percentage breakdowns, and human-readable storage consumption (KB/MB/GB) for loose or organized directories.
• Duplicate & Collision Protection: Automatically detects existing destination files and appends numerical suffixes (file (1).ext) to ensure zero data loss.
• Smart System & Metadata Filtering: Automatically skips critical system files (desktop.ini, .DS_Store, thumbs.db), git metadata (.git, .gitignore), temporary files (.tmp, .crdownload), and log files.
• Rich CLI Reporting: Powered by colorama, featuring formatted ASCII tables detailing processed counts, skipped items, error logs, and execution duration.
• Audit Logging & State History: Maintains JSON history logs for seamless state persistence across sessions and detailed execution logs in logs/organizer.log.

---

Screenshots & Visual Showcase

1. Interactive Main Menu

---

2. File Organization Workflow (Before & After)

• Before Organization (Unorganized Directory):

• Execution Report & CLI Summary:

• After Organization (Clean Category Subfolders):

---

3. Folder Statistics & Analytics

---

4. Safe Undo & Automatic Folder Cleanup

---

Project Architecture

03-Automatic-File-Organizer/
│
├── app.py                   # Main CLI entry point & interactive menu UI
├── config.py                # File categories, extension mappings & ignore rules
├── organizer.py             # Core file organizing engine, dry-run & undo logic
├── report.py                # Formatted ASCII tables & visual report generation
├── logger.py                # Centralized logging configuration & formatting
├── utils.py                 # File filters, size formatting & statistical helpers
├── requirements.txt         # External dependencies (colorama)
├── README.md                # Project documentation
│
├── logs/                    # Runtime application logs directory
│   └── organizer.log        # Timestamped audit logs
│
└── screenshots/             # Visual demonstration assets
    ├── main_menu.png
    ├── before_organization.png
    ├── organization_report.png
    ├── after_organization.png
    ├── folder_statistics.png
    └── undo_operation.png

---

Tech Stack

• Language: Python 3.8+
• Standard Libraries: os, sys, shutil, json, logging, datetime, pathlib
• Third-Party Package:
  • colorama (v0.4.6+) - Cross-platform terminal color output and styling.

---

Installation & Setup

Prerequisites

• Python 3.8 or higher installed on your system.
• Git (optional, for cloning).

Steps

1. Clone the Repository

   git clone https://github.com/sanjansahdev/03-Automatic-File-Organizer.git
   cd 03-Automatic-File-Organizer

2. (Optional) Create a Virtual Environment

   # Windows
   python -m venv venv
   venv\Scripts\activate
   
   # macOS / Linux
   python3 -m venv venv
   source venv/bin/activate

3. Install Dependencies

   pip install -r requirements.txt

---

Usage Guide

Launch the interactive application by executing app.py:

python app.py

Interactive Menu Options

1. [1] Organize Folder (Live Mode) Prompts for a target directory path, validates the path, sorts unorganized files into respective category subdirectories, and renders a summary report.

2. [2] Preview Organization (Dry-Run Mode) Simulates the sorting operation without modifying any files on disk. Highly recommended before performing live operations on critical directories.

3. [3] Undo / Rollback Last Organization Reads the execution state history (organizer_history.json) and reverts files moved during the last run back to their original paths. Automatically removes empty category subfolders created during organization.

4. [4] View Folder Statistics Displays file count, size breakdown, and percentage consumption per category within a specified target directory.

5. [5] Exit Safely exits the application.

---

Configuration & Customization

You can easily extend file category rules, extension mappings, or system file ignore lists in config.py:

# Customizing File Extensions in config.py
FILE_TYPES = {
    "Images": [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg", ".ico", ".tiff", ".raw"],
    "Documents": [".pdf", ".docx", ".doc", ".txt", ".ppt", ".pptx", ".xls", ".xlsx", ".csv", ".odt", ".rtf"],
    "Videos": [".mp4", ".mkv", ".avi", ".mov", ".wmv", ".flv", ".webm", ".m4v"],
    "Music": [".mp3", ".wav", ".aac", ".flac", ".ogg", ".m4a", ".wma"],
    "Archives": [".zip", ".rar", ".7z", ".tar", ".gz", ".bz2", ".iso"],
    "Code": [".py", ".js", ".html", ".css", ".java", ".cpp", ".c", ".cs", ".php", ".json", ".xml", ".yaml", ".yml", ".ts", ".sh", ".sql"],
    "Programs": [".exe", ".msi", ".dmg", ".pkg", ".deb", ".apk"],
    "Spreadsheets": [".xls", ".xlsx", ".csv", ".ods"],
    "Ebooks": [".epub", ".mobi", ".azw3"],
}

# Ignored Files & Extensions
DEFAULT_IGNORED_FILES = {"desktop.ini", ".ds_store", "thumbs.db", ".git", ".gitignore", "organizer_history.json", "organizer.log"}
DEFAULT_IGNORED_EXTENSIONS = {".tmp", ".part", ".crdownload", ".log", ".bak", ".swp"}

---

Logging & History Tracking

• Execution Audit: Every operation is logged with timestamps, levels (INFO/WARNING/ERROR), and details to logs/organizer.log.
• Undo History: Saved in organizer_history.json to store original source paths, destination paths, and created folders for seamless restoration.

---

Contributing

Contributions are welcome! If you'd like to report a bug or suggest a new feature:

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

---

License

Distributed under the MIT License. See LICENSE for more information.

---

Author & Contact

G. Sanjan Sah

• GitHub: @sanjansahdev
• Project Repository: 03-Automatic-File-Organizer

---

Created by G. Sanjan Sah