Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

empty-folder-manager

your-username0MIT1.1.0

Interactive CLI tool for analyzing and removing empty folders from filesystem with .gitignore support and custom glob patterns

cli, filesystem, cleanup, empty-folders, directory, interactive, gitignore, glob, patterns, file-management, disk-cleanup, web-ui

readme

🗂️ Empty Folder Manager

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!

npm version License: MIT

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

From CLI Menu

# 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:

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

Made with ❤️ for developers who love clean filesystems!