CaseMapper

Universal Directory Naming Convention Converter

Transform folder names between any naming convention with a professional CLI and TUI interface.

Features

• 🔄 Multi-Convention Support: snake_case, kebab-case, camelCase, PascalCase, CONSTANT_CASE, dot.case, Title Case
• 🎨 Beautiful TUI: Full-screen terminal interface (optional)
• 📊 Live Analysis: See convention distribution before making changes
• 🔍 Smart Conflict Detection: Handles naming collisions intelligently
• 📝 Session History: Track all operations with SQLite
• ⚙️ Rule Engine: Custom YAML rules for exceptions
• 🔄 Undo Support: Auto-generated undo scripts
• 👁️ Watch Mode: Auto-rename new folders as they're created
• 📊 HTML Reports: Generate beautiful reports
• 🔌 Plugin System: Extend with custom transformations
• 🚀 Zero Dependencies: Works with stdlib only, enhanced with optional packages

Installation

Recommended: pipx (for CLI usage)

# Install pipx if needed
sudo apt install pipx    # Debian/Ubuntu
# or: brew install pipx  # macOS

# Install casemapper
pipx install casemapper              # Basic (no dependencies)
pipx install "casemapper[tui]"       # With TUI interface
pipx install "casemapper[all]"       # All features

Alternative: Virtual Environment

python3 -m venv ~/.casemapper-env
source ~/.casemapper-env/bin/activate
pip install casemapper[all]

Development Installation

git clone https://github.com/jeanbaissari/casemapper.git
cd casemapper
python3 -m venv venv
source venv/bin/activate
pip install -e ".[all,dev]"

Note: Modern Linux distributions (Ubuntu 23.04+, Fedora 38+, Debian 12+) restrict global pip installs (PEP 668). Use pipx or a virtual environment.

Optional Features

pip install casemapper[tui]      # TUI interface (textual)
pip install casemapper[rich]     # Rich terminal output
pip install casemapper[watch]    # Watch mode (watchdog)
pip install casemapper[git]      # Git integration
pip install casemapper[yaml]     # YAML rule engine
pip install casemapper[reports]  # HTML reports
pip install casemapper[all]      # Everything

Quick Start

# Interactive mode (guided setup)
casemapper

# Preview changes (dry run)
casemapper --dry-run

# Convert to kebab-case
casemapper --convention kebab

# Specific directory
casemapper --target ~/projects --convention snake

# Watch mode (auto-rename)
casemapper --watch --target ~/Downloads

# Full TUI interface
casemapper --tui

Usage Examples

Basic Conversion

# Convert all folders in current directory to snake_case
casemapper

# Convert to camelCase, only immediate children
casemapper --convention camel --no-recursive

# Limit recursion depth
casemapper --max-depth 2

Advanced Features

# Exclude patterns
casemapper --exclude node_modules --exclude .git

# Include hidden folders
casemapper --include-hidden

# Generate HTML report
casemapper --report report.html

# View history
casemapper --history

# Undo a session
casemapper --undo 5

As a Library

from casemapper import CaseMapperSettings, FolderScanner, ConversionTarget

# Configure
settings = CaseMapperSettings(
    target_dir="/path/to/folders",
    convention=ConversionTarget.KEBAB_CASE,
    recursive=True
)

# Scan
scanner = FolderScanner()
folders = scanner.scan(settings.target_dir)

# Process...

Configuration

Create ~/.casemapper.yaml:

convention: snake_case
recursive: true
max_depth: 5
exclude_patterns:
  - node_modules
  - .git
  - venv
conflict_strategy: auto-number
include_hidden: false

License

MIT License - see LICENSE file for details.

Author

Jean Baissari