batch-renamer

name	batch-renamer
description	Rename files in bulk using pattern-based rules, regex capture groups, numbering sequences, case conversions, and date-based renaming. Use when renaming multiple files at once, adding prefixes/suffixes, numbering files, or organizing files by date. Triggers include "rename files", "bulk rename", "add prefix to files", "number files", "rename with pattern", "ren command".

batch-renamer

CLI tool for bulk file renaming with preview, undo, and conflict detection.

Quick Start

# Preview renames (no changes applied)
ren "*.jpg" "{date}_{name}{ext}" --dry-run

# Apply renames (shows preview, prompts for confirmation)
ren "*.jpg" "{date}_{name}{ext}"

# Apply without confirmation
ren "*.jpg" "{date}_{name}{ext}" --yes

# Undo last operation
ren undo

Pattern Variables

Variable	Description	Example Input	Example Output
{name}	Filename without extension	photo.jpg	photo
{ext}	Extension with dot	photo.jpg	.jpg
{index}	1-based sequence number	file 3 of 25	3
{index:3}	Zero-padded to N digits	file 3 of 25	003
{date}	Today YYYY-MM-DD	any	2026-03-20
{year}	Current year	any	2026
{month}	Current month MM	any	03
{day}	Current day DD	any	20
{dir}	Parent directory name	/photos/beach/img.jpg	beach
{1}, {2}	Regex capture groups	see --regex	group value

Common Patterns

# Add date prefix
ren "*.jpg" "{date}_{name}{ext}"

# Number files with zero-padding
ren "*.mp3" "{index:3}_{name}{ext}"

# Add suffix before extension
ren "*.png" "{name}_backup{ext}"

# Organize by year
ren "*.jpg" "{year}/{name}{ext}"

# Combine date and index
ren "*.jpg" "{date}_{index:4}_{name}{ext}"

Regex Mode

# --regex "pattern" "output"
# Capture groups referenced as {1}, {2}, ... or {name} for named groups

# Remove IMG_ prefix, keep number
ren --regex "^IMG_(\d+)" "photo_{1}" "*.jpg"

# Reformat date in filename
ren --regex "^(\d{4})-(\d{2})-(\d{2})_(.*)" "{1}{2}{3}_{4}" "*.jpg"

# Named capture groups
ren --regex "(?<year>\d{4})-(?<month>\d{2})" "{year}_{month}" "*.log"

# Non-matching files are skipped silently

Case Conversion

ren --uppercase "*.txt"       # FILENAME.TXT
ren --lowercase "*.TXT"       # filename.txt
ren --titlecase "*.txt"       # Filename.txt
ren --kebab "*.txt"           # file-name.txt
ren --snake "*.txt"           # file_name.txt

Date-Based Renaming

# Prepend today's date
ren --date-prefix "*.jpg"

# Use EXIF date from JPEG metadata (requires exiftool)
ren --date-exif "*.jpg" "{date}_{name}{ext}"

Recursive Mode

# Rename all .txt files in subdirectories
ren --recursive "**/*.txt" "{name}.bak"

# Recursive with ignore
ren --recursive "**/*.js" "{name}.mjs" --ignore node_modules --ignore dist

Batch Mode

# Run multiple rename operations from a config file
ren batch operations.json

# Continue on conflicts instead of aborting
ren batch operations.json --continue-on-conflict

operations.json format:

[
  { "glob": "*.jpg", "pattern": "{date}_{name}{ext}" },
  { "glob": "*.png", "pattern": "{date}_{name}{ext}" }
]

Undo

# Undo the last rename operation
ren undo

# View undo history
ren stats

CLI Reference

Flag	Description
--dry-run	Preview only, no file changes
--yes	Apply without confirmation prompt
--recursive	Walk subdirectories
--ignore <pattern>	Exclude matching paths (repeatable)
--regex <from> <to>	Regex mode with capture groups
--uppercase	Convert to uppercase
--lowercase	Convert to lowercase
--titlecase	Convert to title case
--kebab	Convert to kebab-case
--snake	Convert to snake_case
--date-prefix	Prepend current date
--date-exif	Use EXIF date from JPEG
--force	Apply even with conflicts
--skip-conflicts	Skip conflicting files, rename rest
--continue-on-conflict	Batch mode: continue after conflicts
--no-color	Disable ANSI color output
--version	Show version
--help	Show help

Environment Variables

Variable	Default	Description
BREN_UNDO_PATH	~/.local/share/batch-renamer/undo.json	Path to undo stack file
BREN_NO_COLOR	0	Disable ANSI color (1 to disable)
BREN_DRY_RUN	0	Always run in dry-run mode (1 to enable)
BREN_DEBUG	0	Enable debug logging (1 to enable)

Exit Codes

Code	Meaning
0	Success
1	No files matched the glob pattern
2	Conflicts detected and not resolved
3	Runtime error

Troubleshooting

No files matched - Check that your glob pattern is quoted to prevent shell expansion. Use --dry-run to test patterns safely.

Conflict: destination already exists - Use --skip-conflicts to skip those files, or --force to overwrite.

Undo stack is empty - No previous rename operations to undo in the current session.

EXIF date not found - Install exiftool and ensure the JPEG file has DateTimeOriginal or CreateDate metadata.