empty-folder-manager/README.md

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

# 🗂️ 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](https://badge.fury.io/js/empty-folder-manager.svg)](https://badge.fury.io/js/empty-folder-manager)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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

```bash
# 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

```bash
# 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
```bash
# 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
```bash
# 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
```bash
$ 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
```bash
# CLI with automatic .gitignore support
npx empty-folder-manager

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

### System Cleanup
```bash
# CLI for quick system maintenance
npx empty-folder-manager

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

### Backup Directories
```bash
# 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](https://github.com/your-username/empty-folder-manager/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!**