sd/README.md

sd - s[earch] & d[isplace]

sd is a simple, user-friendly find & replace command line tool.

Features

Painless regular expressions

Use regex syntax that you already know from JavaScript, Python, and Rust. No need to learn special syntax or eccentrisms of sed or awk. Easily access your captured groups with $1, $2.

String-literal mode

In string-literal mode, you don't need to escape any special characters - its simply unnecessary.

Easy to read, easy to write

Find & replace expressions are split up and in most cases unescaped, which contributes to readability and makes it easier to spot errors in your regexes.

Comparison to sed

While sed is frighteningly powerful, sd focuses on doing just one thing and doing it well.

Some cherry-picked examples, where sd shines:

• Replace newlines with commas:
  • sed: sed ':a;N;$!ba;s/\r/,/g' vs
  • sd: sd -r '\r' ','
• Extracting stuff out of strings with special characters
  • sd: echo "{((sample with /path/))}" | sd -r '\{\(\(.*(/.*/)\)\)\}' '$1'
  • sed
    • incorrect, but closest I could get after 15 minutes of struggle
    • echo "{((sample with /path/))}" | sed 's/{((\.\*\(\/.*\/\)))}/\1/g'

Note: although sed has a nicer regex syntax with -r, it is not portable and doesn't work on, say, MacOS or Solaris.

Guide

1. Literal mode. By default, expressions are treated as literals.

> echo "lots((([]))) of special chars" | sd "((([])))" ""
lots of special chars

Use -r or --regex to enable regex.

2. Basic regex use - let's trim some trailing whitespace

> echo "lorem ipsum 23   " | sd -r '\s+$' ''
lorem ipsum 23

3. Capture groups

Indexed capture groups:

> echo "cargo +nightly watch" | sd -r '(\w+)\s+\+(\w+)\s+(\w+)' 'cmd: $1, channel: $2, subcmd: $3'
cmd: cargo, channel: nightly, subcmd: watch

Named capture groups:

> echo "123.45" | sd -r '(?P<dollars>\d+)\.(?P<cents>\d+)' '$dollars dollars and $cents cents'
123 dollars and 45 cents

If you stumble upon any ambiguities, just use ${var} instead of $var:

> echo "123.45" | sd -r '(?P<dollars>\d+)\.(?P<cents>\d+)' '$dollars_dollars and $cents_cents'
 and 
> echo "123.45" | sd -r '(?P<dollars>\d+)\.(?P<cents>\d+)' '${dollars}_dollars and ${cents}_cents'
123_dollars and 45_cents

4. Find & replace in files

> sd "window.fetch" "fetch" -i http.js

That's it.

Do a dry run:

> sd "window.fetch" "fetch" < http.js 

5. Find & replace across project

Good ol' unix philosophy to the rescue.

fd -t f --exec sd 'from "react"' 'from "preact"' -i {}

Same, but with backups (consider version control).

for file in $(fd -t f); do
  cp "$file" "$file.bk"
  sd 'from "react"' 'from "preact"' -i "$file"; 
done