ashlr__search_replace_regex
Regex-based search and replace across multiple files. Returns a diff summary and match count — not the full file contents.
ashlr__search_replace_regex applies a regex search-and-replace across one or more files and returns a compact diff summary (changed lines only). Use it for bulk renames or pattern-based transforms that span multiple files when ashlr__edit_structural doesn't apply (non-TS/JS files, or regex logic that can't be expressed as a symbol rename).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
pattern | string | yes | Regex pattern to search for (ECMAScript regex syntax). |
replacement | string | yes | Replacement string (supports $1, $2 capture group refs; $$ emits a literal $). |
flags | string | no | Optional flags subset; i (case-insensitive), m (multiline), s (dotall), u (unicode). The g flag is always implicit. |
include | string[] | no | ripgrep-style glob patterns to include (e.g. ['src/**/*.ts']). When omitted, all files under roots are candidates. |
exclude | string[] | no | ripgrep-style glob patterns to exclude (e.g. ['/node_modules/']). |
dryRun | boolean | no | If true, return the planned change set (per-file match counts) without writing. Default false. |
maxFiles | number | no | Hard cap on candidate files scanned. Default 200. Overflow is truncated with a warning (not a refusal). |
maxMatchesPerFile | number | no | Hard cap on replacements per file. Default 100. Extra matches are left in place and flagged as capped. |
roots | string[] | no | Search roots (cwd-relative or absolute). Default: [process.cwd()]. Each is cwd-clamped. |
Example
Returns
A compact diff summary:
When to use ashlr__edit_structural instead
For TypeScript/TSX/JS/JSX symbol renames (functions, classes, variables), prefer ashlr__edit_structural — it is scope-aware and won't rename occurrences that shadow the target symbol.
Typical savings
−80% vs ashlr__multi_edit with N edits — one call covers all files, and only match counts + diff lines are returned.
Related
ashlr__edit— single-file literal search/replaceashlr__multi_edit— batch literal editsashlr__edit_structural— AST-aware rename- Capabilities matrix