Skip to content

Commit f84f1c1

Browse files
jlevyclaude
jlevy
and
claude
committed
Simplify and improve documentation formatting
- Rename 'Alternatives' section to 'Comparison to Alternatives' - Simplify Agent Use section, remove redundant comparison table - Improve line wrapping and formatting for better readability - Fix typo: 'everythign' → 'everything' - Make agent documentation more concise and accessible Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
1 parent c56127a commit f84f1c1

4 files changed

Lines changed: 81 additions & 144 deletions

File tree

‎README.md‎

Lines changed: 25 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -122,11 +122,10 @@ extension “.orig”. If directory paths are provided, it applies replacements
122122
to all files in the supplied paths that are not in the exclude pattern.
123123
If no arguments are supplied, it reads from stdin and writes to stdout.
124124

125-
## Alternatives
125+
## Comparison to Alternatives
126126

127-
There are many tools for search/replace and refactoring. Here's how repren compares:
128-
129-
### Comparison
127+
There are many tools for search/replace and refactoring.
128+
Here’s how repren compares:
130129

131130
| 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) |
132131
| --- | --- | --- | --- | --- | --- | --- | --- |
@@ -140,23 +139,26 @@ There are many tools for search/replace and refactoring. Here's how repren compa
140139

141140
**When to use each:**
142141

143-
- **repren**: Bulk renames with file/directory renaming, case preservation, or simultaneous
144-
swaps. Works on any text file with full backup/undo support.
145-
- **sed/awk/perl**: Classic approaches for quick one-liners. See
142+
- **repren**: Bulk renames with file/directory renaming, case preservation, or
143+
simultaneous swaps. Works on any text file with full backup/undo support.
144+
- **sed/awk/perl**: Classic approaches for quick one-liners.
145+
See
146146
[classic approaches](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549).
147147
Often error-prone for complex patterns and lack dry-run mode, simultaneous swaps, or
148148
cross-platform consistency.
149-
- **sd**: Fast sed replacement (2-11x faster than sed), but limited to simple find/replace
150-
without file renaming, case preservation, or multi-pattern swaps.
151-
- **fastmod**: Good for interactive human review of changes, but lacks case preservation,
152-
simultaneous swaps, and file/directory renaming.
149+
- **sd**: Fast sed replacement (2-11x faster than sed), but limited to simple
150+
find/replace without file renaming, case preservation, or multi-pattern swaps.
151+
- **fastmod**: Good for interactive human review of changes, but lacks case
152+
preservation, simultaneous swaps, and file/directory renaming.
153153
- **ast-grep**: Language-aware refactoring where you need to match code structure (e.g.,
154-
function calls, not just text). Use when semantic understanding matters more than speed.
155-
- **comby**: Structural matching across languages without learning AST syntax. Useful when
156-
you need to match code patterns like balanced braces, but overkill for simple text
157-
refactoring.
158-
- **rnr**: File/directory renaming only (no content replacement). Has dry-run by default,
159-
backup option, and undo via dump files. Use repren if you also need content replacement.
154+
function calls, not just text).
155+
Use when semantic understanding matters more than speed.
156+
- **comby**: Structural matching across languages without learning AST syntax.
157+
Useful when you need to match code patterns like balanced braces, but overkill for
158+
simple text refactoring.
159+
- **rnr**: File/directory renaming only (no content replacement).
160+
Has dry-run by default, backup option, and undo via dump files.
161+
Use repren if you also need content replacement.
160162

161163
## Installation
162164

@@ -177,36 +179,13 @@ script somewhere convenient and make it executable.
177179

178180
## Agent Use
179181

180-
### Why Agents Should Use repren
181-
182-
repren is designed for use by AI coding agents (Claude Code, Codex, etc.)
183-
as well as humans.
184-
185-
AST-based tools (ast-grep, Semgrep, ts-morph) can be better for focused, language-aware
186-
semantic refactoring.
187-
But repren is ideal for fast, large code or doc text refactoring, file/directory
188-
renaming, or any serious larger-scale renaming effort:
189-
190-
| Feature | repren | AST tools | Built-in Edit |
191-
| --- | --- | --- | --- |
192-
| Simultaneous renames and swaps (foo↔bar) | ✅ | ❌ | ❌ |
193-
| File/directory renaming | ✅ | Some | ❌ |
194-
| Case-preserving variants | ✅ | ❌ | ❌ |
195-
| Works on any text file | ✅ | ❌ | ✅ |
196-
| Dry runs, backups, undo system | ✅ | ❌ | ❌ |
197-
198-
### JSON Output
199-
200-
Use `--format=json` for machine-parseable output:
201-
202-
```bash
203-
repren --format=json --from=foo --to=bar --full src/
204-
```
205-
206-
### Claude Code Skill
182+
repren is ideal for use by AI coding agents (Claude Code, Codex, etc.)
183+
since it is powerful, simple to use, and self-documenting.
184+
Just tell agents to run `uvx repren@latest --help` and they have everything they need,
185+
including the ability to install it as a skill.
186+
Agents can use `--format=json` for machine-parseable output.
207187

208-
repren includes a built-in skill for [Claude Code](https://claude.com/claude-code), so
209-
Claude can use repren for bulk refactoring tasks.
188+
repren includes a built-in skill for Claude Code or other agents.
210189

211190
**Install:**
212191

‎docs/repren-docs.md‎

Lines changed: 25 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -109,11 +109,10 @@ extension “.orig”. If directory paths are provided, it applies replacements
109109
to all files in the supplied paths that are not in the exclude pattern.
110110
If no arguments are supplied, it reads from stdin and writes to stdout.
111111

112-
## Alternatives
112+
## Comparison to Alternatives
113113

114-
There are many tools for search/replace and refactoring. Here's how repren compares:
115-
116-
### Comparison
114+
There are many tools for search/replace and refactoring.
115+
Here’s how repren compares:
117116

118117
| 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) |
119118
| --- | --- | --- | --- | --- | --- | --- | --- |
@@ -127,23 +126,26 @@ There are many tools for search/replace and refactoring. Here's how repren compa
127126

128127
**When to use each:**
129128

130-
- **repren**: Bulk renames with file/directory renaming, case preservation, or simultaneous
131-
swaps. Works on any text file with full backup/undo support.
132-
- **sed/awk/perl**: Classic approaches for quick one-liners. See
129+
- **repren**: Bulk renames with file/directory renaming, case preservation, or
130+
simultaneous swaps. Works on any text file with full backup/undo support.
131+
- **sed/awk/perl**: Classic approaches for quick one-liners.
132+
See
133133
[classic approaches](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549).
134134
Often error-prone for complex patterns and lack dry-run mode, simultaneous swaps, or
135135
cross-platform consistency.
136-
- **sd**: Fast sed replacement (2-11x faster than sed), but limited to simple find/replace
137-
without file renaming, case preservation, or multi-pattern swaps.
138-
- **fastmod**: Good for interactive human review of changes, but lacks case preservation,
139-
simultaneous swaps, and file/directory renaming.
136+
- **sd**: Fast sed replacement (2-11x faster than sed), but limited to simple
137+
find/replace without file renaming, case preservation, or multi-pattern swaps.
138+
- **fastmod**: Good for interactive human review of changes, but lacks case
139+
preservation, simultaneous swaps, and file/directory renaming.
140140
- **ast-grep**: Language-aware refactoring where you need to match code structure (e.g.,
141-
function calls, not just text). Use when semantic understanding matters more than speed.
142-
- **comby**: Structural matching across languages without learning AST syntax. Useful when
143-
you need to match code patterns like balanced braces, but overkill for simple text
144-
refactoring.
145-
- **rnr**: File/directory renaming only (no content replacement). Has dry-run by default,
146-
backup option, and undo via dump files. Use repren if you also need content replacement.
141+
function calls, not just text).
142+
Use when semantic understanding matters more than speed.
143+
- **comby**: Structural matching across languages without learning AST syntax.
144+
Useful when you need to match code patterns like balanced braces, but overkill for
145+
simple text refactoring.
146+
- **rnr**: File/directory renaming only (no content replacement).
147+
Has dry-run by default, backup option, and undo via dump files.
148+
Use repren if you also need content replacement.
147149

148150
## Installation
149151

@@ -164,36 +166,13 @@ script somewhere convenient and make it executable.
164166

165167
## Agent Use
166168

167-
### Why Agents Should Use repren
168-
169-
repren is designed for use by AI coding agents (Claude Code, Codex, etc.)
170-
as well as humans.
171-
172-
AST-based tools (ast-grep, Semgrep, ts-morph) can be better for focused, language-aware
173-
semantic refactoring.
174-
But repren is ideal for fast, large code or doc text refactoring, file/directory
175-
renaming, or any serious larger-scale renaming effort:
176-
177-
| Feature | repren | AST tools | Built-in Edit |
178-
| --- | --- | --- | --- |
179-
| Simultaneous renames and swaps (foo↔bar) | ✅ | ❌ | ❌ |
180-
| File/directory renaming | ✅ | Some | ❌ |
181-
| Case-preserving variants | ✅ | ❌ | ❌ |
182-
| Works on any text file | ✅ | ❌ | ✅ |
183-
| Dry runs, backups, undo system | ✅ | ❌ | ❌ |
184-
185-
### JSON Output
186-
187-
Use `--format=json` for machine-parseable output:
188-
189-
```bash
190-
repren --format=json --from=foo --to=bar --full src/
191-
```
192-
193-
### Claude Code Skill
169+
repren is ideal for use by AI coding agents (Claude Code, Codex, etc.)
170+
since it is powerful, simple to use, and self-documenting.
171+
Just tell agents to run `uvx repren@latest --help` and they have everything they need,
172+
including the ability to install it as a skill.
173+
Agents can use `--format=json` for machine-parseable output.
194174

195-
repren includes a built-in skill for [Claude Code](https://claude.com/claude-code), so
196-
Claude can use repren for bulk refactoring tasks.
175+
repren includes a built-in skill for Claude Code or other agents.
197176

198177
**Install:**
199178

‎repren/repren.py‎

Lines changed: 25 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -111,11 +111,10 @@
111111
to all files in the supplied paths that are not in the exclude pattern.
112112
If no arguments are supplied, it reads from stdin and writes to stdout.
113113
114-
## Alternatives
114+
## Comparison to Alternatives
115115
116-
There are many tools for search/replace and refactoring. Here's how repren compares:
117-
118-
### Comparison
116+
There are many tools for search/replace and refactoring.
117+
Here’s how repren compares:
119118
120119
| 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) |
121120
| --- | --- | --- | --- | --- | --- | --- | --- |
@@ -129,23 +128,26 @@
129128
130129
**When to use each:**
131130
132-
- **repren**: Bulk renames with file/directory renaming, case preservation, or simultaneous
133-
swaps. Works on any text file with full backup/undo support.
134-
- **sed/awk/perl**: Classic approaches for quick one-liners. See
131+
- **repren**: Bulk renames with file/directory renaming, case preservation, or
132+
simultaneous swaps. Works on any text file with full backup/undo support.
133+
- **sed/awk/perl**: Classic approaches for quick one-liners.
134+
See
135135
[classic approaches](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549).
136136
Often error-prone for complex patterns and lack dry-run mode, simultaneous swaps, or
137137
cross-platform consistency.
138-
- **sd**: Fast sed replacement (2-11x faster than sed), but limited to simple find/replace
139-
without file renaming, case preservation, or multi-pattern swaps.
140-
- **fastmod**: Good for interactive human review of changes, but lacks case preservation,
141-
simultaneous swaps, and file/directory renaming.
138+
- **sd**: Fast sed replacement (2-11x faster than sed), but limited to simple
139+
find/replace without file renaming, case preservation, or multi-pattern swaps.
140+
- **fastmod**: Good for interactive human review of changes, but lacks case
141+
preservation, simultaneous swaps, and file/directory renaming.
142142
- **ast-grep**: Language-aware refactoring where you need to match code structure (e.g.,
143-
function calls, not just text). Use when semantic understanding matters more than speed.
144-
- **comby**: Structural matching across languages without learning AST syntax. Useful when
145-
you need to match code patterns like balanced braces, but overkill for simple text
146-
refactoring.
147-
- **rnr**: File/directory renaming only (no content replacement). Has dry-run by default,
148-
backup option, and undo via dump files. Use repren if you also need content replacement.
143+
function calls, not just text).
144+
Use when semantic understanding matters more than speed.
145+
- **comby**: Structural matching across languages without learning AST syntax.
146+
Useful when you need to match code patterns like balanced braces, but overkill for
147+
simple text refactoring.
148+
- **rnr**: File/directory renaming only (no content replacement).
149+
Has dry-run by default, backup option, and undo via dump files.
150+
Use repren if you also need content replacement.
149151
150152
## Installation
151153
@@ -166,36 +168,13 @@
166168
167169
## Agent Use
168170
169-
### Why Agents Should Use repren
170-
171-
repren is designed for use by AI coding agents (Claude Code, Codex, etc.)
172-
as well as humans.
173-
174-
AST-based tools (ast-grep, Semgrep, ts-morph) can be better for focused, language-aware
175-
semantic refactoring.
176-
But repren is ideal for fast, large code or doc text refactoring, file/directory
177-
renaming, or any serious larger-scale renaming effort:
178-
179-
| Feature | repren | AST tools | Built-in Edit |
180-
| --- | --- | --- | --- |
181-
| Simultaneous renames and swaps (foo↔bar) | ✅ | ❌ | ❌ |
182-
| File/directory renaming | ✅ | Some | ❌ |
183-
| Case-preserving variants | ✅ | ❌ | ❌ |
184-
| Works on any text file | ✅ | ❌ | ✅ |
185-
| Dry runs, backups, undo system | ✅ | ❌ | ❌ |
186-
187-
### JSON Output
188-
189-
Use `--format=json` for machine-parseable output:
190-
191-
```bash
192-
repren --format=json --from=foo --to=bar --full src/
193-
```
194-
195-
### Claude Code Skill
171+
repren is ideal for use by AI coding agents (Claude Code, Codex, etc.)
172+
since it is powerful, simple to use, and self-documenting.
173+
Just tell agents to run `uvx repren@latest --help` and they have everything they need,
174+
including the ability to install it as a skill.
175+
Agents can use `--format=json` for machine-parseable output.
196176
197-
repren includes a built-in skill for [Claude Code](https://claude.com/claude-code), so
198-
Claude can use repren for bulk refactoring tasks.
177+
repren includes a built-in skill for Claude Code or other agents.
199178
200179
**Install:**
201180

‎repren/skills/SKILL.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ allowed-tools: Bash(repren:*), Bash(uvx repren@latest:*), Read, Write
55
---
66
# Repren - Multi-Pattern Search and Replace
77

8-
> **Full documentation: Run `uvx repren@latest --docs` for all options, flags, and advanced
9-
> usage.**
8+
> **Full documentation: Run `uvx repren@latest --docs` for all options, flags, and
9+
> advanced usage.**
1010
1111
Multi-pattern search/replace tool for bulk refactoring with simultaneous replacements,
1212
file/directory renaming, and case-preserving transformations.
@@ -76,8 +76,8 @@ and directories matching the patterns.
7676
uvx repren@latest --from='old_module' --to='new_module' --full src/
7777
```
7878

79-
Renames files and directories, creating parent directories as needed.
80-
Files never clobber: numeric suffixes are added if conflicts arise.
79+
Renames files and directories, creating parent directories as needed. Files never
80+
clobber: numeric suffixes are added if conflicts arise.
8181

8282
### Regex Patterns with Capture Groups
8383

@@ -96,8 +96,8 @@ class Old(\w+) class New\1
9696

9797
### Atomic Operations with Backups
9898

99-
All modifications create `.orig` backup files automatically.
100-
Original files never truncated on errors.
99+
All modifications create `.orig` backup files automatically. Original files never
100+
truncated on errors.
101101

102102
### Dry Run
103103

0 commit comments

Comments
 (0)