Safe Find & Replace: How Not to Break Binaries

When working with real projects (changing a CDN, migration, refactoring) you often need to replace one URL with another in bulk.

At first glance the task seems trivial: sed -i 's|old|new|g' **/* — and you’re done.

In practice this approach is dangerous: the pattern can match binary files.

Careless replacement leads to:

• corruption of binary files (images, PDFs, archives);
• unnecessary changes in git history: binaries are marked as modified;
• inability to roll back if no backup was made.

Below is a procedure that changes only text, leaves binaries untouched, and creates a targeted backup before replacement.

Input data

• Old URL: https://static-old.example-cdn.net
• New URL: https://cdn-new.example-storage.net
• Context: Project with mixed content (HTML, JS, YAML + PNG, JPG, WOFF2).

Procedure

1. Preparation and search (Dry Run)

The key tool is grep -I (ignores binary files even if they contain matching bytes).

First, just see what we are going to change:

# Search recursively, ignore binaries, print list of files
grep -rIl 'https://static-old.example-cdn.net' .

Important: make sure the list contains only text files (no images, fonts, etc.). If everything looks reasonable — proceed.

2. Targeted backup

Don’t copy the entire project — it’s slow and takes space. Save only the files that contain the searched string, preserving hierarchy and metadata.

SEARCH="https://static-old.example-cdn.net"
BACKUP_DIR="backup_before_replace"

mkdir -p "$BACKUP_DIR"

# Copy only files that match
find . -type f -print0 \
  | xargs -0 grep -Il "$SEARCH" \
  | xargs -I{} sh -c 'mkdir -p "$BACKUP_DIR/$(dirname "{}")" && cp -p "{}" "$BACKUP_DIR/{}"'

Now backup_before_replace contains an exact copy of only the files to be changed. Rollback is a simple copy back.

3. Replacement

sed -i behaves differently on Linux (GNU) and macOS (BSD):

• Linux: sed -i 's/old/new/g'
• macOS: sed -i '' 's/old/new/g'

To make the script work everywhere (locally, in CI, on Mac/Linux), use perl — it is identical on all *nix systems.

OLD="https://static-old.example-cdn.net"
NEW="https://cdn-new.example-storage.net"

find . -type f -not -path "./$BACKUP_DIR/*" -print0 \
  | xargs -0 grep -Il "$OLD" \
  | xargs -0 perl -pi -e "s|\Q$OLD\E|$NEW|g"

\Q and \E automatically escape all special characters in the URL (dots, slashes, hyphens) — no need to backslash them manually.

4. Verification

Make sure everything went successfully:

# Should return empty output
grep -rIl "$OLD" . --exclude-dir="$BACKUP_DIR"

# Should show changed files (example: first 5)
grep -rIl "$NEW" . --exclude-dir="$BACKUP_DIR" | head -n 5

You can also run git status or git diff --stat to see the actual changes.

Why this is more reliable

1. grep -I — reliable protection from corrupting binaries.
2. Targeted backup — save only the delta, saving space and time.
3. perl instead of sed — cross-platform stability (Linux, macOS, CI).
4. Variables and clear steps — the script is easy to read and adapt.

TL;DR — Ready snippet for “here and now”

Paste into the terminal and replace the URLs:

SEARCH="https://static-old.example-cdn.net"
REPLACE="https://cdn-new.example-storage.net"
BACKUP="backup_$(date +%s)"

mkdir -p "$BACKUP"

# 1. Targeted backup of only files that match
find . -type f -print0 \
  | xargs -0 grep -Il "$SEARCH" \
  | xargs -I{} sh -c 'mkdir -p "$BACKUP/$(dirname "{}")" && cp -p "{}" "$BACKUP/{}"'

# 2. Safe replacement (perl — works on Linux and macOS)
find . -type f -not -path "./$BACKUP/*" -print0 \
  | xargs -0 grep -Il "$SEARCH" \
  | xargs -0 perl -pi -e "s|\Q$SEARCH\E|$REPLACE|g"

echo "Done! Backup saved in folder $BACKUP"
echo "Rollback (if needed): cp -r $BACKUP/. ."

This approach is safe and works the same across all files: changes affect only text, while binary data remains untouched.