Skip to main content
Blog

Bulk Find-Replace: When Your Editor Stops Being Enough

Every developer knows Ctrl+H. You open find-and-replace in VS Code, type a term, hit Replace All, done — in one file. The problems start when "bulk" means 400 files, 12 projects, or a folder of exports from a CMS that nobody has opened since 2021. At that scale the editor is no longer a tool; it becomes the bottleneck.

This article walks through where editor-based bulk replace works fine, where it silently fails, and when a script or a dedicated bulk replacer is the right answer. Everything here comes from real migration and refactoring work, not theory.

Where the editor is perfectly fine

Serious editors are good at bulk replace and have been for years. VS Code's "Replace in Files" handles workspace-wide changes with per-file diffs you can review. IntelliJ has structural search and replace, which understands the language's syntax tree — you can replace Optional.of(x) with Optional.ofNullable(x) only where x can be null, using variable constraints.

Use the editor when:

  • The set of files is small and known — one module, one component directory.
  • You want to eyeball every change. Per-file diffs in a GUI are the best review surface there is.
  • The replacement is literal text, one or two patterns, and the risk of a wrong match is low.

A rename of a CSS class used in 30 Blade templates? Editor, Replace All, commit. No script needed.

Where the editor starts to lose

1. Scale with review pressure. Replacing a term across 800 files produces 800 diffs. Clicking through them in a GUI takes longer than writing a script, and fatigue guarantees you'll approve a bad one around file 600.

2. Multi-step changes. Real data migrations are rarely one substitution. A typical legacy cleanup looks like: strip HTML entities, normalize quotes, collapse whitespace, fix line endings, remove duplicate lines, then run the actual replace. Five sequential transforms. In an editor you repeat the dialog five times per file group and pray you ran them in the same order everywhere. In a script, the order is in the file, and rerunning it is free.

3. Repeatability. If the replace is part of a migration you'll run on staging, then production, then again next quarter on the next batch of exports, a GUI action is a one-off — it exists only in your muscle memory. A script is a versioned artifact you can put in the repo and code-review.

4. Encoding and line-ending traps. Editors silently re-encode files or flip CRLF to LF depending on their defaults. On a mixed Windows/Linux codebase, one careless Replace-in-Files can rewrite line endings in 200 files and blow the diff up so badly that the real change becomes unreviewable. This is a classic. If line endings need fixing, do it as a deliberate, separate pass with a dedicated tool rather than as a side effect — for example with a line-ending normalizer that converts explicitly instead of by accident.

5. Files the editor can't classify. A naive Replace-in-Files across a project root happily rewrites files in node_modules, build output, vendor directories, and minified bundles. You get a 40,000-line diff where 39,850 lines are noise. Editors offer exclusion globs, but every developer forgets them at least once, and the fix afterwards is painful: git checkout -- node_modules doesn't work if the directory isn't tracked.

What scripts get right

The core argument for scripts is determinism plus composability. A typical Unix one-liner culture evolved around this exact problem: find . -name '*.md' -exec sed -i 's/oldterm/newterm/g' {} +. It's fast, handles thousands of files, and only touches what the glob matches.

But raw sed -i has its own failure modes worth knowing before you trust it:

  • In-place without backup. On GNU sed, -i without a suffix overwrites with no undo. Run it against a git tree, or use -i.bak and clean up.
  • Locale surprises. Case-insensitive matching (s/.../.../gi) depends on the locale; Turkish 'I' problems occasionally bite CI runners configured differently from laptops.
  • Special characters. The delimiter / collides with URLs and paths; escaping a replacement string containing & or \1 is a common source of corrupted output.
  • No dry run. sed doesn't show you what it would change. Always run the same expression without -i first and diff the output.

The professional workflow, regardless of the tool, is always three phases: preview (list matches), replace, verify (diff stats, count of affected files, spot checks). GUI tools blur these phases together; scripts make all three explicit. Skipping the preview phase is how a rename of id ends up inside your uuid strings.

The workflow I actually use

For a real migration — say, moving 300 marketing pages off a legacy CMS export — the sequence looks like this:

  1. Inventory. grep -rl 'old-domain.com' . to find every affected file. Never assume; count.
  2. Preview. Run the replacement expression with output to stdout, sample a dozen files, and read them.
  3. Normalize first, replace second. Cleanup steps before the semantic change: remove broken line breaks from single-source text exports, drop duplicate lines from list-like files. Doing the replace on messy input means you need two variants of the pattern to catch both messy and clean matches.
  4. Replace. Script or bulk text replacer with per-rule controls — one rule set, applied to a curated file list, with a preview of every match before writing.
  5. Verify. git diff --stat — file count and line count must match the inventory from step 1. A mismatch means something was missed or touched twice.
  6. Residual grep. Run the original search again. Zero hits is the definition of done; anything left means your pattern had a variant you didn't cover (Old-Domain.com vs old-domain.com is the classic one).

Steps 1, 5, and 6 are what separates a migration from a hope. They take two minutes and they're the reason the change survives review.

Rules of thumb

  • Under ~20 files with visible diffs: editor. The GUI review surface wins.
  • Hundreds of files, or the same change needed twice: script. Reviewability comes from git diff, not from a dialog.
  • Multi-step text cleanup: script or pipeline tool, in a fixed order — normalize, deduplicate, then replace.
  • Regex replace with capture groups across files: prefer a tool with a match preview over sed. One wrong group reference across 500 files is an afternoon of recovery.
  • Anything touching generated or vendor directories: exclude them explicitly, in writing, before the first run.

Neither approach is wrong. Editors are the fastest path for small, visible changes. Scripts and bulk tools take over the moment scale, repeatability, or multi-step cleanup enters the picture. The mistake isn't picking the "wrong" one — it's running a 900-file GUI replace without a preview, or a blind sed -i over a mixed-encoding tree, and finding out about it in the diff.