To bulk find and replace from a list, put your pairs in a two-column file (the text to find in the first column, the replacement in the second), then apply every row to every file in one run. You can do that with a short PowerShell loop over a CSV, or by importing the CSV into a batch find and replace tool that runs the rows as stacked rules. Either way, the list becomes the single source of truth, so you never retype terms or miss one.
This guide covers how to build the CSV properly, two ways to apply it, and the ordering and matching rules that keep a long list from tripping over itself.
When a list beats typing replacements
- Rebrands and renames. A product, company or feature name changes, along with a dozen related terms.
- Glossaries. Technical writers keep approved terminology in a spreadsheet and need every doc to follow it.
- URL and path migrations. Hundreds of old URLs map to new ones after a site restructure.
- Data clean-ups. Codes, abbreviations or misspellings that need standardizing across many files.
In each case, someone usually already has the mapping in Excel. The goal is to use it directly.
Step 1: build the CSV
Create a spreadsheet with a header row and two columns:
| Find | Replace |
|---|---|
| Acme Widgets Pro | Zenith Tools Pro |
| Acme Widgets | Zenith Tools |
| support@acme-widgets.com | help@zenith-tools.com |
| /products/old-page.html | /tools/new-page.html |
Then save it correctly:
- In Excel, choose File → Save As.
- Pick CSV UTF-8 (Comma delimited) (*.csv) as the file type. Plain "CSV (Comma delimited)" saves in the ANSI code page, which can mangle accented or non-Latin characters.
- Click Save and accept the warning about features that CSV cannot keep.
A few CSV details matter:
- Commas and quotes inside values. Excel wraps those values in double quotes automatically. If you build the file by hand, do the same, and double any quote inside a value (
"He said ""hi"""). - Leading and trailing spaces. A stray space at the end of a cell becomes part of the search term and causes misses. Use Excel's
TRIM()to clean the column. - Empty replacements. An empty Replace cell means "delete this text". Make sure that is what you intend.
Step 2: sort the list
Rows are applied in order, and each one sees the result of the rows before it. Sort so that:
- Longer terms come before shorter terms they contain. Acme Widgets Pro must run before Acme Widgets, which must run before Acme. Otherwise the short term changes part of the long one first, and the long rule finds nothing.
- No replacement creates text that a later row will match, unless that is deliberate.
A quick way to sort by length in Excel: add a helper column with =LEN(A2), sort the table by it from largest to smallest, then delete the helper column before saving.
Step 3a: apply the list with PowerShell
With the CSV saved as rules.csv (headers Find and Replace), this applies every row to every .md file in the folder tree:
$rules = Import-Csv rules.csv -Encoding UTF8
Get-ChildItem -Recurse -File -Filter *.md | ForEach-Object { $t = Get-Content $_.FullName -Raw -Encoding UTF8; $n = $t; foreach ($r in $rules) { $n = $n.Replace($r.Find, $r.Replace) }; if ($n -ne $t) { Set-Content $_.FullName $n -NoNewline -Encoding UTF8; $_.FullName } }
Notes on this script:
.Replace()is literal and case-sensitive, which is usually right for a glossary. Use-replaceif your list contains regex patterns, and[regex]::Escape($r.Find)if it contains literal text with dots or brackets that you want to match case-insensitively.- There is no whole-word option with
.Replace(). To match whole words only, use$n = $n -creplace ('\b' + [regex]::Escape($r.Find) + '\b'), $r.Replace. If a replacement could contain a$, escape it as$$. - Back up the folder first. The script overwrites files and has no undo.
- In Windows PowerShell 5.1,
-Encoding UTF8writes a byte order mark. See our PowerShell replace guide for alternatives.
Step 3b: import the list into a batch tool
If you would rather not maintain a script, Bulk Replace imports whole rule sets from a CSV. The rows become stacked rules that run in order during one pass:
- Choose the folder, include sub-folders, and filter by extension (for example
.md .html .txt). - Import the CSV. Each row becomes a rule, and you can still add or edit rules by hand, or switch individual rules to whole-word, case-sensitive or regex matching.
- Check the before/after preview. Every file and every match is listed, with a total count. Untick any match that should keep the old wording, such as a quote or a historical note.
- Apply. Files are backed up first, one click undoes the whole job, and a timestamped report of files changed and match counts can be exported as CSV for review.
Save the folder, filters and rules as a Bulk Replace project so the same glossary can be applied to new files later in two clicks.
Keeping the list maintainable
A replacement list tends to grow and get reused. A few habits keep it reliable:
- Add a notes column in your master spreadsheet explaining why each row exists, then export only the Find and Replace columns to the CSV you run.
- Keep the list in version control or a shared folder, so everyone applies the same version.
- Remove rows that no longer match anything after a few runs, so the list stays readable.
Checking the result
- Search for every old term. Any that remain point to a rule that was shadowed by an earlier one, a case difference, or a stray space in the CSV.
- Search for doubled results. Text like Zenith Tools Tools or Zenith Zenith shows that two rules overlapped.
- Spot-check a few files in full, especially those with the most matches.
Common problems
| Symptom | Likely cause | Fix |
|---|---|---|
| A term was not replaced anywhere | A shorter row ran first, or the cell has a trailing space | Sort by length; TRIM the column |
| Accented terms garbled | CSV saved as ANSI, or read with the wrong encoding | Save as CSV UTF-8 and read it as UTF-8 |
| Part of a longer word changed | No whole-word matching | Turn on whole word, or use \b in regex |
| Only some capitalizations changed | Case-sensitive matching | Add a row for each case form |
For more on ordering and overlapping terms, see how to find and replace multiple words at once. If the list is a documentation glossary, our guide to updating terminology across documentation covers plurals, capitalization and code samples.
Frequently asked questions
What should a find and replace CSV look like?
Two columns: the text to find and the text to replace it with, one pair per row. Save it as CSV UTF-8 if any terms contain accented or special characters.
Can I make the CSV in Excel?
Yes. Put the find terms in column A and the replacements in column B, then use File, Save As and choose CSV UTF-8 (Comma delimited).
What if one term is part of another term in my list?
Sort the list so longer terms come first, or use whole-word matching, so a short term does not change part of a longer one before its own rule runs.
