How to replace text in files with sed

A sed replacement is useful when a hostname, path, label, or setting appears in local text files and the edit must be repeatable from the terminal. A careless in-place command can rewrite too much or leave no restore path, so preview the substitution first and keep a backup while changing real files.

The substitution command uses the form s#old#new#g in these examples. The # delimiter keeps URL-style text readable without escaping every slash, and the final g flag replaces every matching occurrence on each line instead of only the first one.

Use sed -i.bak when saving the replacement back to the same files. The attached .bak suffix creates a backup beside each edited file and avoids the GNU sed versus BSD/macOS sed difference around no-backup in-place edits.

1. Work from files whose target text has already been identified.

   service.conf

   api_url=https://api-old.example/v1
   status_url=https://api-old.example/status
   owner=platform

   worker.conf

   api_url=https://api-old.example/worker
   queue=default

   Use copies while testing a broad replacement. Once the pattern is confirmed, run the same command against the real files.

2. Preview the replacement against one file without changing it.

   $ sed 's#https://api-old.example#https://api-new.example#g' service.conf
   api_url=https://api-new.example/v1
   status_url=https://api-new.example/status
   owner=platform

   The command prints the changed text to the terminal because it does not use -i. If the preview changes the wrong text, stop here and narrow the search string.

   Related: How to preview replacements with sed

3. Apply the replacement in place with a backup suffix.

   $ sed -i.bak 's#https://api-old.example#https://api-new.example#g' service.conf worker.conf

   The -i.bak form creates service.conf.bak and worker.conf.bak before saving the edited files. Keep the suffix attached to -i so the command works on both GNU sed and BSD/macOS sed.

   In the replacement side of a sed substitution, & expands to the matched text and backslashes can change the replacement. Preview first when the new value contains either character.

4. Confirm the edited files contain the new value.

   $ grep -n 'api-new.example' service.conf worker.conf
   service.conf:1:api_url=https://api-new.example/v1
   service.conf:2:status_url=https://api-new.example/status
   worker.conf:1:api_url=https://api-new.example/worker

5. Check that the old value is gone from the edited files.

   $ grep -n 'api-old.example' service.conf worker.conf

   No output means grep did not find the old hostname in the edited files.

6. Review the backups before deleting them.

   $ grep -n 'api-old.example' service.conf.bak worker.conf.bak
   service.conf.bak:1:api_url=https://api-old.example/v1
   service.conf.bak:2:status_url=https://api-old.example/status
   worker.conf.bak:1:api_url=https://api-old.example/worker

   If the replacement was too broad, restore a file with cp service.conf.bak service.conf and rerun sed with a narrower search string.

   Tool: Text Diff Comparator can compare an edited file with its .bak copy before the backup is deleted.