Cao Yi

Find and Replace a String in a Directory (Recursive)

Index

You’re not just replacing text—you’re performing bulk surgery on your codebase. Do it carefully.

---

The Problem

You want to:

1. Find all files containing a string
2. Replace that string across many files
3. Do it safely (without breaking things)

This is a common task in real projects: renaming variables, updating API endpoints, or fixing repeated mistakes.

---

Mental Model (How This Actually Works)

Think of the pipeline like this:

[grep] → [xargs] → [sed/perl]
  │         │           │
  │         │           └── Modify file content
  │         └────────────── Pass file list safely
  └──────────────────────── Find matching files

Or more concretely:

Search → Select files → Apply transformation

Each tool does one job—and does it well.

---

Step 1: Find Files Containing a String

grep -rl "abcabc" .

What this does

• -r (or --recursive): Search recursively
• -l (or --files-with-matches): Print only filenames (not matching lines)
• .: Start from current directory

Important detail

• -r does NOT follow symbolic links
• Use -R if you want to follow them

---

Step 2: Replace the String in All Matching Files

Safe and robust version (recommended)

grep -rlZ --exclude-dir=.git "abcabc" . \
| xargs -0 perl -pi -e 's/abcabc/cdecde/g'

Why this version is solid

• Handles filenames with spaces/newlines (-Z + -0)
• Works on both Linux and macOS
• Uses perl for reliable regex behavior
• Avoids modifying .git directory

---

Breaking It Down

1. grep -rlZ

• -r: recursive search
• -l: output filenames only
• -Z (or --null): separate filenames with \0 (null character)

Why this matters:

Normal output:
file one.txt
file two.txt

With -Z:
file one.txt\0file two.txt\0

This avoids breaking on spaces or weird filenames.

---

2. xargs -0

• Reads null-separated input
• Safely passes filenames to the next command

Without this, filenames like:

my file.txt

would break your command.

---

3. perl -pi -e

• -p: loop over each line
• -i: edit files in place
• -e: execute code

Replacement:

s/abcabc/cdecde/g

• 's/abcabc/cdecde/g': Substitution command, replace all matches on each line
  • s/ = substitute
  • abcabc = search pattern (treated as basic regex)
  • cdecde = replacement string
  • g = global — replace all occurrences on each line (not just the first one).

---

Why Not Just Use sed?

You can, but there are pitfalls.

Linux (GNU sed)

sed -i 's/abcabc/cdecde/g'

macOS (BSD sed)

sed -i '' 's/abcabc/cdecde/g'

That tiny difference ('') breaks scripts across platforms.

👉 This is why perl is often the safer default.

---

Safety First (Don’t Skip This)

1. Preview before changing anything

Dry-run / preview (before actual replacement):

# just list affected files
grep -rl "abcabc" .

Or inspect matches:

# show actual matching lines
grep -r "abcabc" .

---

2. Create backups

grep -rlZ "abcabc" . \
| xargs -0 perl -pi.bak -e 's/abcabc/cdecde/g'

This creates a .bak backup of every modified file.

---

3. Exclude dangerous directories

Always consider excluding:

• .git
• node_modules
• build
• dist

Example:

grep -rlZ \
  --exclude-dir=.git \
  --exclude-dir=node_modules \
  "abcabc" .

---

Common Variations

Case-insensitive replace

grep -rilZ "abcabc" . \
| xargs -0 perl -pi -e 's/abcabc/cdecde/gi'

---

Replace whole words only

perl -pi -e 's/\babcabc\b/cdecde/g'

(\b works reliably in Perl, not always in sed)

---

Limit to specific file types

grep -rlZ --include="*.txt" --include="*.md" "abcabc" .

---

A Practical Rule of Thumb

If you remember nothing else, remember this:

Search with grep, pass safely with xargs -0, modify with perl.

That combination is:

• portable
• safe
• predictable

---

Final Recommended Command

grep -rlZ --exclude-dir=.git "abcabc" . \
| xargs -0 perl -pi -e 's/abcabc/cdecde/g'

---

Closing Thought

Bulk replacement is powerful—but also dangerous.

A careless command can:

• break production code
• corrupt data
• introduce subtle bugs

So treat it like any other engineering change:

• preview
• isolate
• verify
• then execute

Do that, and this becomes one of the most useful tools in your workflow.

This site is open source. Improve this page.