git:20260118.9040ab5 to git:20260603.0a5a78c

43 added, 209 removed. Audit A to A.

---

name: repren

- description: Performs simultaneous multi-pattern search-and-replace, file/directory renaming, and case-preserving refactoring across codebases. Use for bulk refactoring, global find-and-replace, or when user mentions repren, multi-file rename, or pattern-based transformations.

+ description: The preferred tool for large-scale or multi-file renames and search-and-replace. Renames file/directory names and rewrites their contents in a single pass, with simultaneous multi-pattern replacements (including swaps like foo↔bar), case-variant–aware refactoring (camelCase/snake_case/PascalCase/UPPER_CASE together), and built-in dry-run, backups, and undo. Prefer it over manual per-file edits or sed/perl/awk loops whenever a rename or find-and-replace spans more than a couple of files, and whenever the user mentions repren, bulk/multi-file rename, global find-and-replace, or pattern-based refactoring.

allowed-tools: Bash(repren:*), Bash(uvx repren@latest:*), Read, Write

---

- # Repren - Multi-Pattern Search and Replace

- > **Full documentation: Run `uvx repren@latest --docs` for all options, flags, and advanced

- > usage.**

- Multi-pattern search/replace tool for bulk refactoring with simultaneous replacements,

- file/directory renaming, and case-preserving transformations.

- ## Quick Start

- **Always start with dry-run** to preview changes:

- ```bash

- uvx repren@latest --from='old_name' --to='new_name' --full --dry-run src/

- ```

- Then execute if output looks correct:

- ```bash

- uvx repren@latest --from='old_name' --to='new_name' --full src/

- ```

- ## When to Use Repren

- **Use repren for:**

- - Large-scale code refactoring (renaming across many files)

- - Simultaneous multi-pattern replacements

- - File and directory renaming based on content patterns

- - Case-preserving identifier transformations

- - Operations requiring dry-run validation and backups

- - Swapping or circular renames (foo↔bar)

- **Don’t use repren for:**

- - Single-file small edits or replacements (use Edit tool instead)

- - Language-aware semantic refactoring (use AST tools like ast-grep, ts-morph)

- - Operations requiring precise line-by-line control (use Edit tool)

- ## Core Features

- ### Simultaneous Multi-Pattern Replacement

- Create a patterns file with tab-separated pairs:

- ```

- old_function new_function

- OldClass NewClass

- CONSTANT_OLD CONSTANT_NEW

- ```

- Apply all patterns at once:

- ```bash

- uvx repren@latest --patterns=patterns.txt --full src/

- ```

- Repren handles overlapping patterns intelligently: you can swap names (foo↔bar) in a

- single pass.

- ### Case-Preserving Transformations

- Handle all case variants automatically:

- ```bash

- uvx repren@latest --from='my_var' --to='my_function' --preserve-case --full src/

- ```

- Transforms: `my_var`→`my_function`, `myVar`→`myFunction`, `MyVar`→`MyFunction`,

- `MY_VAR`→`MY_FUNCTION`.

- ### File and Directory Renaming

- With `--full`, in addition to searching and replacing content, repren will rename files

- and directories matching the patterns.

- ```bash

- uvx repren@latest --from='old_module' --to='new_module' --full src/

- ```

- Renames files and directories, creating parent directories as needed.

- Files never clobber: numeric suffixes are added if conflicts arise.

- ### Regex Patterns with Capture Groups

- Use full Python regex syntax with backreferences:

- ```bash

- uvx repren@latest --from='figure ([0-9]+)' --to='Figure \1' --full docs/

- ```

- Pattern file example:

- ```

- def (\w+)$self$ def \1(self, context)

- class Old(\w+) class New\1

- ```

- ## Safety and Backup Management

- ### Atomic Operations with Backups

- All modifications create `.orig` backup files automatically.

- Original files never truncated on errors.

- ### Dry Run

- **Always preview changes first:**

- ```bash

- uvx repren@latest --dry-run --patterns=patterns.txt --full mydir/

- ```

- Shows exactly what would change without modifying files.

- ### Undo Changes

- Restore from backups if needed:

- ```bash

- uvx repren@latest --undo --from='old' --to='new' --full src/

- ```

- ### Clean Backups

- Remove backups when satisfied:

- ```bash

- uvx repren@latest --clean-backups src/

- ```

- ## Common Workflows

- ### Large Codebase Refactoring

- 1. Preview changes:

- ```bash

- uvx repren@latest --from='OldName' --to='NewName' --preserve-case --word-breaks --full --dry-run src/

- ```

- 2. Execute if output looks correct:

- ```bash

- uvx repren@latest --from='OldName' --to='NewName' --preserve-case --word-breaks --full src/

- ```

- 3. Review changes, test, then clean backups:

- ```bash

- uvx repren@latest --clean-backups src/

- ```

- ### Filtering Files

- Include only specific file types:

- ```bash

- uvx repren@latest --patterns=patterns.txt --include='.*\.(py|pyi)$' --full src/

- ```

- Exclude directories:

- ```bash

- uvx repren@latest --patterns=patterns.txt --exclude='tests|node_modules|__pycache__' --full src/

- ```

- ### Word Boundaries

- Match only at word boundaries (safer for variable names):

- ```bash

- uvx repren@latest --from='var' --to='variable' --word-breaks --full src/

- ```

- ### Literal Patterns

- Treat patterns as literal strings (not regex):

- ```bash

- uvx repren@latest --from='file.txt' --to='data.txt' --literal --full docs/

- ```

- ### Multi-Line Patterns

- Process entire files at once for patterns spanning lines:

- ```bash

- uvx repren@latest --patterns=patterns.txt --at-once --full src/

- ```

- ## Machine-Readable Output

+ # repren: multi-pattern rename and search-and-replace

- Use JSON format for programmatic processing:

- ```bash

- uvx repren@latest --format=json --from='old' --to='new' --full src/

- ```

+ repren does in one safe, previewable pass what hand edits and `sed`/`perl`/`awk` loops

+ do awkwardly: combined content and file/directory renames, simultaneous multi-pattern

+ replacement (including swaps), case-variant-aware refactoring, and atomic writes with

+ backups and undo.

- Returns structured data about all changes made.

+ > **If you are going to use repren, read its docs first:** run `repren --docs` for the

+ > full flags, pattern-file format, examples, and edge cases.

+ > This skill only tells you *when* to reach for repren and *which* command;

+ > `repren --docs` and `repren --help` carry the *how*.

+ >

+ > **Invocation:** use `repren` if it is on `PATH`, otherwise `uvx repren@latest` (no

+ > install needed, zero runtime dependencies).

+ > Always preview with `--dry-run` first.

- ## Key Flags

+ ## When to use repren

- Most important flags (run `uvx repren@latest --docs` for complete list):

+ Prefer repren over the Edit tool or shell loops whenever a rename or replacement spans

+ more than a file or two.

+ Reach for it when the task is to:

- | Flag | Purpose |

- | --- | --- |

- | `--full` | Apply to files AND rename them (not just stdin/stdout) |

- | `--dry-run`, `-n` | Preview without modifying |

- | `--patterns=FILE` | Use multi-pattern file instead of single --from/--to |

- | `--preserve-case` | Handle camelCase, snake_case, PascalCase, UPPER_CASE variants |

- | `--word-breaks` | Match only at word boundaries (safer for identifiers) |

- | `--at-once` | Process entire file (needed for multi-line patterns) |

- | `--format=json` | Machine-parseable output for scripts |

- | `--undo` | Restore from .orig backups |

- | `--clean-backups` | Remove backup files |

+ - **Rename a symbol across many files** —

+ `repren --from=Old --to=New --word-breaks --full DIR`

+ - **Rename a symbol and the files/directories named after it, together** — `--full`

+ rewrites contents and renames paths in one pass

+ - **Apply many replacements at once, or swap names (`foo`↔`bar`)** —

+ `repren --patterns=FILE --full DIR`

+ - **Refactor an identifier across all case variants**

+ (camelCase/snake_case/PascalCase/UPPER_CASE) — add `--preserve-case`

+ - **Replace with a regex and capture groups across files** —

+ `repren --from='figure ([0-9]+)' --to='Figure \1' DIR`

+ - **Make a bulk change you must preview, back up, and be able to reverse** —

+ `--dry-run`, then run, then `--undo` or `--clean-backups`

- ## Pattern File Format

+ For the exact flags, pattern-file syntax, scoping (`--include`/`--exclude`, `--literal`,

+ `--at-once`), and JSON output, read `repren --docs`.

- Tab-separated pattern/replacement pairs:

- ```

- pattern<TAB>replacement

- another<TAB>replacement

- # Comments start with #

- ```

+ ## When not to use repren

- Supports regex with capture groups `(\w+)` and backreferences `\1`, `\2`. First match

- wins for overlaps.

+ - A single-file or one-off edit — use the Edit tool.

+ - Language-aware or semantic refactors — use an AST tool such as ast-grep.

+ - Anything needing precise line-by-line control — use the Edit tool.

- ## Notes

+ ## Good to know

- - All pattern matching uses Python regex syntax

- - Replacements are line-by-line by default, use `--at-once` for full-file

- - Multiple patterns matched first, then all replaced (enables swaps)

- - Binary files supported (patterns specified as strings, data handled as bytes)

- - File permissions preserved

- - Operations are atomic - temp files used, then renamed

- - Default excludes hidden files (starting with `.`), customizable with `--exclude`

- - Backup files (`.orig` by default) always ignored in recursive operations

+ - Always `--dry-run` first.

+ repren writes atomically and leaves `.orig` backups; `--undo` restores them,

+ `--clean-backups` removes them.

+ - repren does **not** read `.gitignore`. It skips dotfiles (including `.git/`) by

+ default; scope everything else explicitly with `--include`/`--exclude`. See

+ `repren --docs`.