diff --git a/README.md b/README.md index e998043..016a156 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ * * * -✨ **NEW:** [v2.0.0-rc1](https://github.com/jlevy/repren/releases/tag/2.0.0-rc1) is out, +✨ **NEW:** [v2.0.0](https://github.com/jlevy/repren/releases/tag/2.0.0) is out, refreshed for Python 3.10-3.14 and agent use! -It’s self-documenting so just tell Claude Code to run `uvx repren@latest --help` and +It's self-documenting so tell Claude Code to run `uvx repren@latest --help` and install as a skill.✨ * * * @@ -124,21 +124,39 @@ If no arguments are supplied, it reads from stdin and writes to stdout. ## Alternatives -Aren’t there standard tools for this already? - -It’s a bit surprising, but not really. -Getting the features right is a bit tricky, I guess. -The -[standard](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549) -[answers](http://stackoverflow.com/questions/6840332/rename-multiple-files-by-replacing-a-particular-pattern-in-the-filenames-using-a) -like *sed*, *perl*, *awk*, *rename*, *Vim* macros, or even IDE refactoring tools, often -cover specific cases, but tend to be error-prone or not offer specific features you -probably want. Things like nondestructive mode, file renaming as well as search/replace, -multiple simultaneous renames/swaps, or renaming enclosing parent directories. -Also many of these vary by platform, which adds to the corner cases. -Inevitably you end up digging through the darker corners of a man page, doing -semi-automated things in an IDE, or writing hacked scripts that are an embarrassment to -share. +There are many tools for search/replace and refactoring. Here's how repren compares: + +### Comparison + +| Feature | repren | [sed/awk/perl](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549) | [sd](https://github.com/chmln/sd) | [fastmod](https://github.com/facebookincubator/fastmod) | [ast-grep](https://ast-grep.github.io/) | [comby](https://comby.dev/) | [rnr](https://github.com/ismaelgv/rnr) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Simultaneous edits and swaps (foo↔bar) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| File/directory renaming | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | +| Case-preserving variants | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| Language-agnostic | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Structural/AST-aware | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | +| Interactivity | Dry run, backups, undo | ❌ | ❌ | Interactive review | Interactive review | Interactive review | Dry run, backups, undo | +| Dependencies | Python 3.10+ (no other deps) | Varies (OS/shell) | Binary (Rust) | Binary (Rust) | Binary (Rust) | Binary (OCaml) | Binary (Rust) | + +**When to use each:** + +- **repren**: Bulk renames with file/directory renaming, case preservation, or simultaneous + swaps. Works on any text file with full backup/undo support. +- **sed/awk/perl**: Classic approaches for quick one-liners. See + [classic approaches](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549). + Often error-prone for complex patterns and lack dry-run mode, simultaneous swaps, or + cross-platform consistency. +- **sd**: Fast sed replacement (2-11x faster than sed), but limited to simple find/replace + without file renaming, case preservation, or multi-pattern swaps. +- **fastmod**: Good for interactive human review of changes, but lacks case preservation, + simultaneous swaps, and file/directory renaming. +- **ast-grep**: Language-aware refactoring where you need to match code structure (e.g., + function calls, not just text). Use when semantic understanding matters more than speed. +- **comby**: Structural matching across languages without learning AST syntax. Useful when + you need to match code patterns like balanced braces, but overkill for simple text + refactoring. +- **rnr**: File/directory renaming only (no content replacement). Has dry-run by default, + backup option, and undo via dump files. Use repren if you also need content replacement. ## Installation diff --git a/docs/repren-docs.md b/docs/repren-docs.md index 6cb5bd2..ed36f83 100644 --- a/docs/repren-docs.md +++ b/docs/repren-docs.md @@ -111,21 +111,39 @@ If no arguments are supplied, it reads from stdin and writes to stdout. ## Alternatives -Aren’t there standard tools for this already? - -It’s a bit surprising, but not really. -Getting the features right is a bit tricky, I guess. -The -[standard](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549) -[answers](http://stackoverflow.com/questions/6840332/rename-multiple-files-by-replacing-a-particular-pattern-in-the-filenames-using-a) -like *sed*, *perl*, *awk*, *rename*, *Vim* macros, or even IDE refactoring tools, often -cover specific cases, but tend to be error-prone or not offer specific features you -probably want. Things like nondestructive mode, file renaming as well as search/replace, -multiple simultaneous renames/swaps, or renaming enclosing parent directories. -Also many of these vary by platform, which adds to the corner cases. -Inevitably you end up digging through the darker corners of a man page, doing -semi-automated things in an IDE, or writing hacked scripts that are an embarrassment to -share. +There are many tools for search/replace and refactoring. Here's how repren compares: + +### Comparison + +| Feature | repren | [sed/awk/perl](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549) | [sd](https://github.com/chmln/sd) | [fastmod](https://github.com/facebookincubator/fastmod) | [ast-grep](https://ast-grep.github.io/) | [comby](https://comby.dev/) | [rnr](https://github.com/ismaelgv/rnr) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Simultaneous edits and swaps (foo↔bar) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| File/directory renaming | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | +| Case-preserving variants | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| Language-agnostic | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Structural/AST-aware | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | +| Interactivity | Dry run, backups, undo | ❌ | ❌ | Interactive review | Interactive review | Interactive review | Dry run, backups, undo | +| Dependencies | Python 3.10+ (no other deps) | Varies (OS/shell) | Binary (Rust) | Binary (Rust) | Binary (Rust) | Binary (OCaml) | Binary (Rust) | + +**When to use each:** + +- **repren**: Bulk renames with file/directory renaming, case preservation, or simultaneous + swaps. Works on any text file with full backup/undo support. +- **sed/awk/perl**: Classic approaches for quick one-liners. See + [classic approaches](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549). + Often error-prone for complex patterns and lack dry-run mode, simultaneous swaps, or + cross-platform consistency. +- **sd**: Fast sed replacement (2-11x faster than sed), but limited to simple find/replace + without file renaming, case preservation, or multi-pattern swaps. +- **fastmod**: Good for interactive human review of changes, but lacks case preservation, + simultaneous swaps, and file/directory renaming. +- **ast-grep**: Language-aware refactoring where you need to match code structure (e.g., + function calls, not just text). Use when semantic understanding matters more than speed. +- **comby**: Structural matching across languages without learning AST syntax. Useful when + you need to match code patterns like balanced braces, but overkill for simple text + refactoring. +- **rnr**: File/directory renaming only (no content replacement). Has dry-run by default, + backup option, and undo via dump files. Use repren if you also need content replacement. ## Installation diff --git a/repren/repren.py b/repren/repren.py index 7c468b3..eaaed81 100755 --- a/repren/repren.py +++ b/repren/repren.py @@ -113,21 +113,39 @@ ## Alternatives -Aren’t there standard tools for this already? - -It’s a bit surprising, but not really. -Getting the features right is a bit tricky, I guess. -The -[standard](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549) -[answers](http://stackoverflow.com/questions/6840332/rename-multiple-files-by-replacing-a-particular-pattern-in-the-filenames-using-a) -like *sed*, *perl*, *awk*, *rename*, *Vim* macros, or even IDE refactoring tools, often -cover specific cases, but tend to be error-prone or not offer specific features you -probably want. Things like nondestructive mode, file renaming as well as search/replace, -multiple simultaneous renames/swaps, or renaming enclosing parent directories. -Also many of these vary by platform, which adds to the corner cases. -Inevitably you end up digging through the darker corners of a man page, doing -semi-automated things in an IDE, or writing hacked scripts that are an embarrassment to -share. +There are many tools for search/replace and refactoring. Here's how repren compares: + +### Comparison + +| Feature | repren | [sed/awk/perl](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549) | [sd](https://github.com/chmln/sd) | [fastmod](https://github.com/facebookincubator/fastmod) | [ast-grep](https://ast-grep.github.io/) | [comby](https://comby.dev/) | [rnr](https://github.com/ismaelgv/rnr) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Simultaneous edits and swaps (foo↔bar) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| File/directory renaming | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | +| Case-preserving variants | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| Language-agnostic | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Structural/AST-aware | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | +| Interactivity | Dry run, backups, undo | ❌ | ❌ | Interactive review | Interactive review | Interactive review | Dry run, backups, undo | +| Dependencies | Python 3.10+ (no other deps) | Varies (OS/shell) | Binary (Rust) | Binary (Rust) | Binary (Rust) | Binary (OCaml) | Binary (Rust) | + +**When to use each:** + +- **repren**: Bulk renames with file/directory renaming, case preservation, or simultaneous + swaps. Works on any text file with full backup/undo support. +- **sed/awk/perl**: Classic approaches for quick one-liners. See + [classic approaches](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549). + Often error-prone for complex patterns and lack dry-run mode, simultaneous swaps, or + cross-platform consistency. +- **sd**: Fast sed replacement (2-11x faster than sed), but limited to simple find/replace + without file renaming, case preservation, or multi-pattern swaps. +- **fastmod**: Good for interactive human review of changes, but lacks case preservation, + simultaneous swaps, and file/directory renaming. +- **ast-grep**: Language-aware refactoring where you need to match code structure (e.g., + function calls, not just text). Use when semantic understanding matters more than speed. +- **comby**: Structural matching across languages without learning AST syntax. Useful when + you need to match code patterns like balanced braces, but overkill for simple text + refactoring. +- **rnr**: File/directory renaming only (no content replacement). Has dry-run by default, + backup option, and undo via dump files. Use repren if you also need content replacement. ## Installation diff --git a/repren/skills/SKILL.md b/repren/skills/SKILL.md index 468d1a9..e3571c4 100644 --- a/repren/skills/SKILL.md +++ b/repren/skills/SKILL.md @@ -1,11 +1,11 @@ --- 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. -allowed-tools: Bash(repren:*), Bash(uvx repren:*), Read, Write +allowed-tools: Bash(repren:*), Bash(uvx repren@latest:*), Read, Write --- # Repren - Multi-Pattern Search and Replace -> **Full documentation: Run `uvx repren --docs` for all options, flags, and advanced +> **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, @@ -15,12 +15,12 @@ file/directory renaming, and case-preserving transformations. **Always start with dry-run** to preview changes: ```bash -uvx repren --from='old_name' --to='new_name' --full --dry-run src/ +uvx repren@latest --from='old_name' --to='new_name' --full --dry-run src/ ``` Then execute if output looks correct: ```bash -uvx repren --from='old_name' --to='new_name' --full src/ +uvx repren@latest --from='old_name' --to='new_name' --full src/ ``` ## When to Use Repren @@ -51,7 +51,7 @@ CONSTANT_OLD CONSTANT_NEW Apply all patterns at once: ```bash -uvx repren --patterns=patterns.txt --full src/ +uvx repren@latest --patterns=patterns.txt --full src/ ``` Repren handles overlapping patterns intelligently: you can swap names (foo↔bar) in a @@ -61,7 +61,7 @@ single pass. Handle all case variants automatically: ```bash -uvx repren --from='my_var' --to='my_function' --preserve-case --full src/ +uvx repren@latest --from='my_var' --to='my_function' --preserve-case --full src/ ``` Transforms: `my_var`→`my_function`, `myVar`→`myFunction`, `MyVar`→`MyFunction`, @@ -73,7 +73,7 @@ With `--full`, in addition to searching and replacing content, repren will renam and directories matching the patterns. ```bash -uvx repren --from='old_module' --to='new_module' --full src/ +uvx repren@latest --from='old_module' --to='new_module' --full src/ ``` Renames files and directories, creating parent directories as needed. @@ -83,7 +83,7 @@ Files never clobber: numeric suffixes are added if conflicts arise. Use full Python regex syntax with backreferences: ```bash -uvx repren --from='figure ([0-9]+)' --to='Figure \1' --full docs/ +uvx repren@latest --from='figure ([0-9]+)' --to='Figure \1' --full docs/ ``` Pattern file example: @@ -103,7 +103,7 @@ Original files never truncated on errors. **Always preview changes first:** ```bash -uvx repren --dry-run --patterns=patterns.txt --full mydir/ +uvx repren@latest --dry-run --patterns=patterns.txt --full mydir/ ``` Shows exactly what would change without modifying files. @@ -112,14 +112,14 @@ Shows exactly what would change without modifying files. Restore from backups if needed: ```bash -uvx repren --undo --from='old' --to='new' --full src/ +uvx repren@latest --undo --from='old' --to='new' --full src/ ``` ### Clean Backups Remove backups when satisfied: ```bash -uvx repren --clean-backups src/ +uvx repren@latest --clean-backups src/ ``` ## Common Workflows @@ -128,64 +128,64 @@ uvx repren --clean-backups src/ 1. Preview changes: ```bash -uvx repren --from='OldName' --to='NewName' --preserve-case --word-breaks --full --dry-run src/ +uvx repren@latest --from='OldName' --to='NewName' --preserve-case --word-breaks --full --dry-run src/ ``` 2. Execute if output looks correct: ```bash -uvx repren --from='OldName' --to='NewName' --preserve-case --word-breaks --full src/ +uvx repren@latest --from='OldName' --to='NewName' --preserve-case --word-breaks --full src/ ``` 3. Review changes, test, then clean backups: ```bash -uvx repren --clean-backups src/ +uvx repren@latest --clean-backups src/ ``` ### Filtering Files Include only specific file types: ```bash -uvx repren --patterns=patterns.txt --include='.*\.(py|pyi)$' --full src/ +uvx repren@latest --patterns=patterns.txt --include='.*\.(py|pyi)$' --full src/ ``` Exclude directories: ```bash -uvx repren --patterns=patterns.txt --exclude='tests|node_modules|__pycache__' --full src/ +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 --from='var' --to='variable' --word-breaks --full src/ +uvx repren@latest --from='var' --to='variable' --word-breaks --full src/ ``` ### Literal Patterns Treat patterns as literal strings (not regex): ```bash -uvx repren --from='file.txt' --to='data.txt' --literal --full docs/ +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 --patterns=patterns.txt --at-once --full src/ +uvx repren@latest --patterns=patterns.txt --at-once --full src/ ``` ## Machine-Readable Output Use JSON format for programmatic processing: ```bash -uvx repren --format=json --from='old' --to='new' --full src/ +uvx repren@latest --format=json --from='old' --to='new' --full src/ ``` Returns structured data about all changes made. ## Key Flags -Most important flags (run `uvx repren --docs` for complete list): +Most important flags (run `uvx repren@latest --docs` for complete list): | Flag | Purpose | | --- | --- | diff --git a/tests/golden-tests-expected.log b/tests/golden-tests-expected.log index 89d25fa..4284b4b 100644 --- a/tests/golden-tests-expected.log +++ b/tests/golden-tests-expected.log @@ -809,7 +809,7 @@ run --skill | head -5 --- 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. -allowed-tools: Bash(repren:*), Bash(uvx repren:*), Read, Write +allowed-tools: Bash(repren:*), Bash(uvx repren@latest:*), Read, Write ---