Bulk File Renamer

A simple, intuitive bulk file renaming tool with support for static patterns, regular expressions, and optional AI-generated names using Google Gemini.

Features

• Static Pattern Renaming: Use patterns like IMG_###.jpg for sequential numbering
• Regular Expression Support: Advanced search and replace with regex
• AI-Generated Names: Optional integration with Google Gemini for intelligent file naming
• Dry Run Mode: Preview changes before execution
• Input Validation: Comprehensive error handling and user confirmation
• Modular Design: Clean, extensible architecture for easy customization

Installation

# Clone the repository
git clone https://github.com/0x-Decrypt/bulk-renamer.git
cd bulk-renamer

# Install dependencies
pip install -r requirements.txt

# Or install directly with pip
pip install -e .

Quick Start

CLI Usage

# Static pattern renaming
python -m bulk_renamer --directory ./photos --pattern "IMG_###.jpg"

# Regular expression renaming
python -m bulk_renamer --directory ./docs --regex "s/old_name/new_name/g"

# AI-generated names (requires API key)
python -m bulk_renamer --directory ./images --ai-rename --api-key your_gemini_key

# Dry run (preview only)
python -m bulk_renamer --directory ./files --pattern "doc_###.txt" --dry-run

Configuration

Create a config.yaml file:

gemini:
  api_key: "your_api_key_here"
  model: "gemini-2.0-flash-exp"
  
defaults:
  dry_run: true
  backup: true
  confirmation: true

Testing

Run the test suite:

python -m pytest tests/ -v

Architecture

The project follows a modular design with clear separation of concerns:

• core/ - Core renaming logic and strategies
• strategies/ - Different renaming strategy implementations
• cli/ - Command-line interface
• config/ - Configuration management
• utils/ - Utility functions and validation

Contributing

1. Fork the repository
2. Create a feature branch
3. Follow the coding guidelines (max 25 lines per function)
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details.