ashlr

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

ParameterTypeRequiredDescription
patternstringyesRegex pattern to search for (ECMAScript regex syntax).
replacementstringyesReplacement string (supports $1, $2 capture group refs; $$ emits a literal $).
flagsstringnoOptional flags subset; i (case-insensitive), m (multiline), s (dotall), u (unicode). The g flag is always implicit.
includestring[]noripgrep-style glob patterns to include (e.g. ['src/**/*.ts']). When omitted, all files under roots are candidates.
excludestring[]noripgrep-style glob patterns to exclude (e.g. ['/node_modules/']).
dryRunbooleannoIf true, return the planned change set (per-file match counts) without writing. Default false.
maxFilesnumbernoHard cap on candidate files scanned. Default 200. Overflow is truncated with a warning (not a refusal).
maxMatchesPerFilenumbernoHard cap on replacements per file. Default 100. Extra matches are left in place and flagged as capped.
rootsstring[]noSearch roots (cwd-relative or absolute). Default: [process.cwd()]. Each is cwd-clamped.

Example

{
  "tool": "ashlr__search_replace_regex",
  "arguments": {
    "pattern": "console\\.log\\(",
    "replacement": "logger.debug(",
    "include": ["src/**/*.ts"],
    "dryRun": true
  }
}

Returns

A compact diff summary:

Replaced 14 occurrences across 6 files:
  src/auth/handler.ts        3 replacements
  src/auth/middleware.ts     2 replacements
  ...

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.

On this page