Weekly Textsmith Nugget: Find and Replace Across Your Entire Project

One of the first moments when you truly appreciate the Unix philosophy is when you realize that editing one file and editing one thousand files are fundamentally the same operation.

Suppose you have just renamed a chapter, changed a product name, or decided that every occurrence of programming should instead read shell scripting. Opening every Markdown document in an editor would be tedious.

This is exactly the sort of repetitive task that textsmiths automate.

Replacing text in the current directory

If all your Markdown files are in the current directory, sed can edit them in place:

sed -i 's/programming/shell scripting/g' *.md

Breaking this down:

• -i edits the files in place.
• s/.../.../ means substitute one string for another.
• g means replace every occurrence on each line.
• *.md applies the command to every Markdown file.

A task that might take twenty minutes by hand finishes in a fraction of a second.

But what about subdirectories?

Real projects usually contain many folders.

Imagine a Quarto project like this:

.
├── posts/
├── primer/
├── workshops/
└── notes/

Now *.md is no longer enough because it only sees the current directory.

Instead, let find locate every Markdown file and pass them to sed.

The modern and safe approach is:

find . -name '*.md' -exec \
    sed -i 's/programming/shell scripting/g' {} +

Here’s what happens:

• find . starts searching from the current directory.
• -name '*.md' limits the search to Markdown files.
• -exec runs another command on the files found.
• {} is replaced by the filenames.
• + tells find to process many files at once, making the operation efficient.

The result is a project-wide replacement with a single command.

Preview before editing

Good textsmiths inspect before they modify.

To see which files contain the text first:

grep -R "programming" .

Or, using the faster modern tool:

rg "programming"

Once you’re satisfied that the matches are correct, run the sed command.

This “search first, replace second” habit prevents unpleasant surprises.

Handling spaces safely

Suppose your project contains filenames like

My First Post.md

Using find with -exec handles these safely without extra effort.

Avoid constructions such as:

find . -name '*.md' | xargs sed ...

unless you understand how to make xargs handle spaces correctly (typically with -print0 and xargs -0).

The -exec form is often easier to read and safer for beginners.

The Textsmith Workflow

Most bulk editing follows the same four-step pattern:

1. Search for the text.
2. Review the matches.
3. Replace automatically.
4. Verify the results.

Notice how little typing is involved. The real work is thinking carefully about what should change, not repeatedly pressing Ctrl+H in dozens of editor windows.

Quick Reference

Forge Wisdom

A textsmith does not edit files one by one.

A textsmith describes the transformation, then lets the computer perform it everywhere.

That is one of the quiet superpowers of plain text: once your work is stored as text, the entire Unix toolbox becomes your editor.

• Weekly Nugget

• Bulk Renaming
• Sed
• Search-and-Replace