An interactive CLI tool for analyzing and removing empty folders from your filesystem efficiently and safely, with support for .gitignore files and custom glob patterns. Now includes a web UI for enhanced usability!

Features

🔧 Configure Path: Set the directory to analyze
⚡ Configure Speed: Choose from 5 speed presets (Turbo to Ultra Gentle)
🎯 Configure Filters: Set up .gitignore support and custom ignore patterns
🔍 Run Analysis: Find all empty folders recursively with intelligent filtering
📊 Show Stats: Display detailed analysis results including ignored folders
🗑️ Remove Folders: Clean up empty folders with dry-run option
💾 Persistent Storage: Analysis results are saved and can be reused
🚀 Disk-Friendly: Gentle on your disk with built-in delays and batch processing
🎨 Beautiful Interface: Native emojis and clean CLI design
🌐 Web UI: Modern web interface for enhanced usability
🖥️ Multiple Interfaces: CLI, Web UI, and Desktop app

Installation

Using npx (Recommended)

# Run CLI directly without installation
npx empty-folder-manager

# Run Web UI directly without installation
npx empty-folder-manager --ui

# Or install globally
npm install -g empty-folder-manager

Using npm

# Install globally
npm install -g empty-folder-manager

# Run the CLI tool
empty-folder-manager

# Run the Web UI
empty-folder-manager --ui

Local Installation

# Clone or download the script
git clone https://github.com/your-username/empty-folder-manager.git
cd empty-folder-manager

# Make executable and run CLI
chmod +x remove-empty-folders.js
./remove-empty-folders.js

# Or run Web UI
node remove-empty-folders.js --ui

# Or with npm scripts
npm run ui

Quick Start

CLI Interface

# Run with npx (no installation needed)
npx empty-folder-manager

# Follow the interactive prompts to:
# 1. Configure the path to analyze
# 2. Set up filtering options (optional)
# 3. Run analysis to find empty folders
# 4. Review results and remove folders

Web UI Interface

# Launch web UI directly
npx empty-folder-manager --ui

# Or use short form
npx empty-folder-manager -u

# Or via npm script
npm run ui

# The web interface will open at http://localhost:3000

# Start CLI normally
npx empty-folder-manager

# Then select option 7 "Launch Web UI" from the menu
# The CLI will automatically install dependencies and launch the web interface.
# After closing the Web UI (e.g., with Ctrl+C in its terminal output), you will be returned to the CLI menu.

Interface Options

🖥️ Command Line Interface (CLI)

Interactive menu: Step-by-step guided experience
Keyboard-driven: Perfect for terminal users and automation
Lightweight: No additional dependencies required
Cross-platform: Works on Windows, macOS, and Linux

🌐 Web User Interface

Modern design: Clean, responsive web interface
Real-time progress: Live updates during analysis
Visual feedback: Progress bars and status indicators
Browser-based: Works in any modern web browser
Persistent settings: Configuration saved in browser storage

🖥️ Desktop Application (Tauri)

Native performance: Built with Rust and Tauri
File system integration: Native file dialogs and permissions
Cross-platform: Windows, macOS, and Linux binaries
Standalone: No browser or Node.js required

Command Line Options

# Show help
empty-folder-manager --help
empty-folder-manager -h

# Launch web UI
empty-folder-manager --ui
empty-folder-manager -u

# Run interactive CLI (default)
empty-folder-manager

NPM Scripts

# Start CLI interface
npm start

# Launch web UI
npm run ui
npm run web

# Install and run locally
npm install
npm start

Filtering Features

🔍 GitIgnore Support

Automatic Detection: Finds and loads .gitignore files from the target directory and parent directories
Standard Patterns: Respects all standard .gitignore syntax including negation patterns (!)
Hierarchical Loading: Loads .gitignore files from current directory up to the analysis root

🎯 Custom Glob Patterns

Flexible Patterns: Add your own ignore patterns using glob syntax
Common Patterns: Built-in patterns for .git, node_modules, .DS_Store, etc.
Pattern Testing: Test patterns against specific paths before running analysis

📋 Supported Pattern Examples

node_modules/          # Ignore node_modules directories
*.log                  # Ignore all .log files
.git/                  # Ignore .git directories
build/                 # Ignore build directories
temp*                  # Ignore anything starting with "temp"
!important.log         # Don't ignore important.log (negation)

Speed Presets

Choose the right speed for your system and needs:

🚀 Turbo (Fastest): No delays, 500 folder batches - Maximum speed
⚡ Fast: 10ms delays, 200 folder batches - Good for modern SSDs
🐢 Normal (Balanced): 50ms delays, 100 folder batches - Default, works well everywhere
🌱 Gentle (Disk-friendly): 100ms delays, 50 folder batches - Good for older HDDs
🐌 Ultra Gentle (Very slow, very safe): 250ms delays, 25 folder batches - Maximum safety

Usage Examples

CLI Interface

# Interactive CLI with menu
npx empty-folder-manager

# The tool will guide you through:
# 1. Configure Path: Set the directory you want to analyze
# 2. Configure Speed: Choose your preferred processing speed
# 3. Configure Filters: Set up .gitignore support and custom patterns
# 4. Run Analysis: Scan for empty folders with intelligent filtering
# 5. Show Stats: View analysis results and filtering statistics
# 6. Remove Folders: Choose dry-run or actual removal
# 7. Launch Web UI: Switch to web interface
# 8. Exit: Quit the application

Web UI Interface

# Launch web UI
npx empty-folder-manager --ui

# Features available in web interface:
# - Visual configuration forms
# - Real-time progress tracking
# - Interactive results display
# - Drag-and-drop path selection (where supported)
# - Persistent browser-based settings

Safety Features

✅ Dry-run mode: Preview what would be removed without making changes
✅ Confirmation prompts: Multiple confirmations before actual deletion
✅ Error handling: Graceful handling of permission errors and inaccessible folders
✅ Intelligent filtering: Respects .gitignore files and custom patterns
✅ Configurable speed: Choose from 5 speed presets to match your system
✅ Batch processing: Processes folders in batches for better performance
✅ Cross-interface consistency: Same safety features across CLI and Web UI

Configuration Files

The tool creates configuration files in the directory where you run it:

.empty-folders-config.json: Stores your configured path, speed settings, and filter preferences
.analysis/: Directory containing analysis results
analysis-{hash}.json: Analysis data for each configured path including filtering statistics

Requirements

Node.js 14.0.0 or higher
Read/write permissions for the directories you want to analyze
For Web UI: Modern web browser (Chrome, Firefox, Safari, Edge)

Example Output

CLI Interface

╔══════════════════════════════════════════════════════════════╗
║                    🗂️  Empty Folder Manager 🗂️                ║
║                                                              ║
║           Clean up your filesystem efficiently! 🚀          ║
╚══════════════════════════════════════════════════════════════╝

📋 Available Options:

  1️⃣  Configure Path     - Set the directory to analyze
  2️⃣  Configure Speed    - Adjust processing speed
  3️⃣  Configure Filters  - Set up .gitignore and custom patterns
  4️⃣  Run Analysis       - Find all empty folders
  5️⃣  Show Stats         - Display analysis results
  6️⃣  Remove Folders     - Clean up empty folders
  7️⃣  Launch Web UI      - Open web interface
  8️⃣  Exit              - Quit the application

📁 Current Path: /home/user/Documents
⚡ Current Speed: 🐢 Normal (Balanced)
🔍 GitIgnore: ✅ Enabled
🎯 Custom Patterns: 3 pattern(s)

Web UI Launch

$ npx empty-folder-manager --ui
🚀 Launching Empty Folder Manager Web UI...

📦 Installing web UI dependencies...
✅ Dependencies installed successfully!

🌐 Starting web server...
🗂️ Empty Folder Manager Web UI running on http://localhost:3000
📁 Open your browser and navigate to the URL above to get started!

Performance Tips

SSD users: Use Turbo or Fast speed for maximum performance
HDD users: Use Gentle or Ultra Gentle to avoid overwhelming your disk
Network drives: Use Ultra Gentle for best reliability
Large directories: Start with Gentle speed to test, then increase if needed
Heavy filtering: More ignore patterns may slow down analysis slightly
Web UI: Use for visual feedback and easier configuration
CLI: Use for automation and scripting scenarios

Common Use Cases

Development Projects

# CLI with automatic .gitignore support
npx empty-folder-manager

# Web UI for visual project cleanup
npx empty-folder-manager --ui

System Cleanup

# CLI for quick system maintenance
npx empty-folder-manager

# Web UI for detailed system analysis
npx empty-folder-manager --ui

Backup Directories

# CLI for automated backup cleanup
npx empty-folder-manager

# Web UI for interactive backup management
npx empty-folder-manager --ui

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - feel free to use and modify as needed!

Support

If you encounter any issues or have questions:

Check the Issues page
Create a new issue with details about your problem
Include your Node.js version and operating system

Made with ❤️ for developers who love clean filesystems!

Keywords

empty-folder-manager