FolderForge

A cross-platform GUI utility engineered to streamline directory structure generation and automated file organization from selected files or tabular spreadsheets (Excel .xlsx/.xls, .csv). The tool provides a non-blocking, multi-threaded execution model with responsive real-time progress tracking, live path sanitization, undo/redo capabilities, multi-batch lifecycle tracking, and automatic file name collision resolution 📂➡️🌳

➡️ Read more about the project, its features, and development in my Medium story or visit the Interactive Showcase.

Table of Contents

• Overview
• Key Features
• Installation
• Usage
• Project Structure
• Development
• Known Issues
• Contributing
• License
• Contact

Overview

FolderForge bridges the gap between digital data organization and filesystem automation. It provides a modern graphical interface to construct deep, multi-tier directory trees instantly — either by organizing unmanaged files on disk or by parsing hierarchical tabular data directly from spreadsheets.

Instead of manually creating nested subfolders or writing bespoke file transfer scripts, FolderForge automates the entire lifecycle. It sanitizes illegal operating system characters on the fly, prevents data loss through automated filename indexing, provides cell-level undo/redo histories, and maintains full visual status awareness across continuous batch processing cycles.

Problem it Solves

• Manual Organization Overhead: Eliminates the tedious and error-prone process of manually creating hundreds of nested client, department, or project subfolders.
• Spreadsheet-to-Folder Disconnect: Converts multi-column spreadsheet architectures directly into physical directory structures on disk in a single click.
• Illegal Filesystem Characters: Automatically sanitizes forbidden OS characters (:*?"<>|\) in real time, preventing runtime filesystem exceptions while safely preserving forward slashes (/) for directory nesting.
• Destination Overwrite Hazards: Protects existing data with built-in numeric collision resolution (e.g., report (1).pdf), ensuring files are never overwritten unintentionally.
• UI Freezes on Large Batches: Decouples the processing engine into a dedicated background worker thread with real-time status updates.

Typical Workflow

1. Launch the application and select your ingestion workflow (File Mode or Excel / CSV Mode).
2. Add files or import a multi-column spreadsheet.
3. Configure your destination path (adjacent to source files or inside a custom directory) and select your file action (Move, Copy, or Create Folders Only).
4. Refine folder names using live sanitization, date/time stamping shortcuts (📅 + Date, ⏰ + Date & Time), or individual cell undo/redo (Cmd+Z / Ctrl+Z).
5. Launch the process, monitor progress, and instantly reveal the generated hierarchy in Finder or Explorer upon completion.

Key Features

• Dual Ingestion Modes:
  • File Mode: Organizes user-selected source files into structured folders based on editable per-row destination paths.
  • Excel / CSV Mode: Ingests tabular spreadsheets and translates sequential column levels (Level 1, Level 2, ...) into deeply nested folder trees.
• Live On-the-Fly Path Sanitization: Replaces forbidden OS characters with underscores in real time, highlights modified entries with warning colors, and strips trailing spaces and periods.
• Undo / Redo History Support: Each folder input cell is equipped with deep stack history supporting Cmd+Z / Ctrl+Z (Undo) and Cmd+Shift+Z / Ctrl+Y (Redo).
• One-Click Date & Time Stamping: Dedicated toolbar buttons insert formatted timestamps (YYYY-MM-DD or YYYY-MM-DD_HH-MM-SS) at the active cursor position or batch-prepend them across selected rows.
• Flexible File Operation Strategies: Choose between Move (Cut), Copy (Safe Archive), or Create Folders Only without touching source files.
• Automatic Collision Resolution: Automatically handles file naming conflicts at destination by appending incremental numerical indices (filename (1).ext).
• Reactive Multi-Batch Lifecycle Badges: Tracks items across sequential runs in the same session with dynamic, color-coded status badges (Pending, ✏ Modified, ✔ Moved/Copied/Created (This Run), ✔ (Prev Batch), and — Skipped).
• Timestamped Spreadsheet Synchronization: In Excel/CSV mode, automatically saves an updated, timestamped spreadsheet reflecting all expanded subfolder columns.
• Dark / Light Mode & Native GUI: Automatically detects macOS system appearance and applies high-contrast theme palettes across all custom widgets.
• Auto-Reveal in File Manager: Includes a dedicated button to open the target folder immediately in macOS Finder, Windows File Explorer, or Linux file managers.

Installation

Prerequisites

• Python 3.7+
• A graphical desktop environment is required to run the tkinter-based GUI.

Clone the Repository

git clone https://github.com/sztaroszta/FolderForge.git
cd FolderForge

Install Dependencies

You can install the required dependency using pip:

pip install -r requirements.txt

Alternatively, install the dependency manually:

pip install openpyxl

Usage

1. Run the application:

python folder_forge.py

2. Choose Ingestion Workflow:

• Workflow A — File Mode (Organizing Files into Folders): Click "➕ Add Files..." to select files. Each row displays the original file name and an editable destination folder field. Configure destination settings (adjacent to original files or under a custom base directory) and choose a file action:

  • Move (Cut): Transfers original files into the generated folders.
  • Copy (Keep original files safe): Duplicates files into newly generated folders.
  • Create Folders Only: Constructs the folders without moving or copying files.

  Use 📅 + Date or ⏰ + Date & Time to insert timestamps into folder names, or edit paths manually (forward slashes / create nested subdirectories).

  

• Workflow B — Excel / CSV Mode (Generating Trees from Spreadsheets): Click "📊 Import Excel / CSV" to load a spreadsheet. Toggle the "First row is header" checkbox if your table includes header labels.

  • Each column is automatically parsed as a folder hierarchy level (Level 1, Level 2, etc.).
  • Forward slashes (/) in cells are supported to create deep nested paths dynamically.
  • Select your base destination directory where the folder tree will be generated.

  

3. Execute and Review Results:

• Click "🚀 Process Selected", "⚡ Process All Files", or "📁 Create Folders Only" to begin background execution.
• Upon completion, a comprehensive summary report displays the total number of directories created, files transferred, collision conflicts resolved, and any errors encountered.
• Click "📂 Open Destination in Finder / Explorer" to immediately open and verify the generated directory structure in your system file manager.

Project Structure

FolderForge/
├── assets/                 # Contains screenshots of the application's UI
├── folder_forge.py         # Main script containing the GUI and processing logic
├── .gitignore              # Git ignore file for Python projects
├── LICENSE                 # GNU General Public License v3 (GPLv3) File
├── README.md               # Project documentation
└── requirements.txt        # List of dependencies

• folder_forge.py: Contains the complete multi-threaded application including theme detection, custom controls, path sanitization algorithms, table rendering, and file operations.
• assets/: Contains user interface previews, banners, and modal dialog screenshots.
• LICENSE: Defines the usage rights under the GNU General Public License v3 (GPLv3).

Development

Guidelines for contributors:

If you wish to contribute or enhance FolderForge:

• Coding Guidelines: Follow Python best practices (PEP 8). Use meaningful variable names and add clear comments or docstrings.
• Testing: Before submitting changes, please test them locally with various files and spreadsheets to ensure existing functionality is not broken.
• Issues/Pull Requests: Please open an issue or submit a pull request on GitHub for enhancements or bug fixes.

Known Issues

• Test Environment: This code has been tested only on macOS. Users running it on Windows or Linux may encounter different behavior.
• Spreadsheet Formulas: When importing .xlsx files, cell values are evaluated via data_only=True. Complex unevaluated formulas without cached values may load as empty strings.
• Platform Dependency: The "Open Destination in Finder / Explorer" feature attempts to detect the OS (macOS/Windows/Linux), but may behave differently on specific Linux distributions depending on the desktop environment.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or fix.
3. Commit your changes with descriptive messages.
4. Push to your fork and submit a pull request.

For major changes, please open an issue first to discuss the proposed changes.

License

Distributed under the GNU General Public License v3 (GPLv3). See LICENSE for full details.

Contact

---

For questions, feedback, or support, please open an issue on the GitHub repository or contact me directly:

Project Showcase: starosta.app

Plant the data, grow the directory tree! 🌱📂

Version: 7

Concept Date: 2025-05-24