rename-patterns

# rename-patterns

Reference guide for batch-renamer pattern variable syntax.

## Pattern Syntax

Patterns are string templates with `{variable}` placeholders. Everything outside `{}` is literal text.

```
prefix_{name}{ext}       ->  prefix_photo.jpg
{name}_v2{ext}           ->  photo_v2.jpg
{index:3}_{name}{ext}    ->  001_photo.jpg
{date}_{name}{ext}       ->  2026-03-20_photo.jpg
```

## Variable Reference

### File Variables

```
{name}     filename without extension
           photo.jpg  ->  photo
           report.2026.pdf  ->  report.2026

{ext}      extension with leading dot
           photo.jpg  ->  .jpg
           archive.tar.gz  ->  .gz

{dir}      immediate parent directory name
           /home/user/photos/beach/img.jpg  ->  beach
```

### Index Variables

```
{index}    1-based sequence number, no padding
           1, 2, 3, ... 25

{index:N}  zero-padded to N digits
           {index:3}  ->  001, 002, ... 025
           {index:4}  ->  0001, 0002, ... 0025
           {index:2}  ->  01, 02, ... 99
```

### Date Variables

Date is captured once at operation start - consistent across all files.

```
{date}     full date YYYY-MM-DD
           2026-03-20

{year}     four-digit year
           2026

{month}    two-digit month with zero-padding
           03

{day}      two-digit day with zero-padding
           20
```

### Regex Capture Groups

Only available in `--regex` mode.

```
{1}        first capture group
{2}        second capture group
{name}     named group (?<name>...)
```

## Pattern Examples by Use Case

### Add prefix

```
{date}_{name}{ext}        2026-03-20_photo.jpg
backup_{name}{ext}        backup_photo.jpg
{year}_{name}{ext}        2026_photo.jpg
```

### Add suffix

```
{name}_final{ext}         photo_final.jpg
{name}_{date}{ext}        photo_2026-03-20.jpg
{name}_{index:3}{ext}     photo_001.jpg
```

### Number files

```
{index:3}_{name}{ext}     001_photo.jpg
{index:4}{ext}            0001.jpg
{date}_{index:3}{ext}     2026-03-20_001.jpg
```

### Organize into subdirectories

```
{year}/{name}{ext}        2026/photo.jpg
{year}/{month}/{name}{ext}  2026/03/photo.jpg
{dir}/{index:3}_{name}{ext}  beach/001_photo.jpg
```

### Replace entire filename

```
{index:4}{ext}            0001.jpg, 0002.jpg
{date}_{index:3}{ext}     2026-03-20_001.jpg
```

## Regex Mode Patterns

```bash
# Input regex    Output pattern
# Capture groups {1}, {2} etc.

# Remove prefix
ren --regex "^OLD_(.*)" "{1}" "*.txt"
# OLD_report.txt  ->  report.txt

# Reorder date parts YYYY-MM-DD -> DD-MM-YYYY
ren --regex "^(\d{4})-(\d{2})-(\d{2})" "{3}-{2}-{1}" "*.log"
# 2026-03-20_app.log  ->  20-03-2026_app.log

# Extract number and reformat
ren --regex "IMG_(\d+)" "photo_{1}" "*.jpg"
# IMG_0042.jpg  ->  photo_0042.jpg

# Named groups (more readable)
ren --regex "(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})" "{day}.{month}.{year}" "*.jpg"
# 2026-03-20_shot.jpg  ->  20.03.2026_shot.jpg
```

## Rules and Edge Cases

**No-op detection** - If from and to are the same, the file is marked skipped (not an error).

**Conflict detection** - If two source files map to the same destination, both are flagged as conflicts.

**Pattern with no variables** - If the pattern produces the same name for every file, it is an error (all files would conflict).

**Extension handling** - `{ext}` includes the dot. To change extension, omit `{ext}` and write the new extension literally: `{name}.bak`.

**Empty extension** - Files without extensions have `{ext}` expand to empty string.

**Index ordering** - Files are sorted alphabetically before indexing. Index 1 is the alphabetically first file.

**Subdirectory creation** - If the pattern produces a path containing a directory separator, the directory is created automatically if it does not exist.

## Combining with Flags

```bash
# Pattern + recursive
ren --recursive "**/*.jpg" "{date}_{name}{ext}"

# Pattern + dry-run (preview only)
ren "*.txt" "{index:3}_{name}{ext}" --dry-run

# Regex + recursive + yes
ren --regex "^IMG_(\d+)" "photo_{1}" "**/*.jpg" --recursive --yes
```