1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
# sd - s[earch] & d[isplace]
`sd` is an intuitive find & replace CLI.
## The Pitch
Why use it over any existing tools?
**Painless regular expressions**
`sd` uses regex syntax that you already know from JavaScript and Python. Forget about dealing with quirks of `sed` or `awk` - get productive immediately.
**String-literal mode**
Non-regex find & replace. No more backslashes or remembering which characters are special and need to be escaped.
**Easy to read, easy to write**
Find & replace expressions are split up, which makes them easy to read and write. No more messing with unclosed and escaped slashes.
**Smart, common-sense defaults**
Defaults follow common sense and are tailored for typical daily use.
## Comparison to sed
While sed does a whole lot more, `sd` focuses on doing just one thing and doing it well.
Some cherry-picked examples, where `sd` shines:
- Simpler syntax for replacing all occurrences:
- sd: `sd before after`
- sed: `sed s/before/after/g`
- Replace newlines with commas:
- sd: `sd '\n' ','`
- sed: `sed ':a;N;$!ba;s/\n/,/g'`
- Extracting stuff out of strings containing slashes:
- sd: `echo "sample with /path/" | sd '.*(/.*/)' '$1'`
- sed: use different delimiters every time depending on expression so that the command is not completely unreadable
- `echo "sample with /path/" | sed -E 's/.*(\\/.*\\/)/\1/g'`
- `echo "sample with /path/" | sed -E 's|.*(/.*/)|\1|g'`
- In place modification of files:
- sd: `sd before after file.txt`
- sed: you need to remember to use `-e` or else some platforms will consider the next argument to be a backup suffix
- `sed -i -e 's/before/after/g' file.txt`
## Benchmarks
**Simple replacement on ~1.5 gigabytes of JSON**
`hyperfine -w 3 'sed -E "s/\"/\'/g" *.json >/dev/null' 'sd "\"" "\'" *.json >/dev/null' --export-markdown out.md`
| Command | Mean [s] | Min…Max [s] |
|:---|---:|---:|
| `sed -E "s/\"/'/g" *.json >/dev/null` | 2.338 ± 0.008 | 2.332…2.358 |
| `sed "s/\"/'/g" *.json >/dev/null` | 2.365 ± 0.009 | 2.351…2.378 |
| `sd "\"" "'" *.json >/dev/null` | **0.997 ± 0.006** | 0.987…1.007 |
Result: ~2.35 times faster
**Regex replacement on a ~55M json file**:
```
hyperfine \
'sed -E "s:(\w+):\1\1:g" dump.json >/dev/null'\
"sed 's:\(\w\+\):\1\1:g' dump.json >/dev/null"\
'sd "(\w+)" "$1$1" dump.json >/dev/null'
```
| Command | Mean [s] | Min…Max [s] |
|:---|---:|---:|
| `sed -E "s:(\w+):\1\1:g" dump.json >/dev/null` | 11.315 ± 0.215 | 11.102…11.725 |
| `sed 's:\(\w\+\):\1\1:g' dump.json >/dev/null` | 11.239 ± 0.208 | 11.057…11.762 |
| `sd "(\w+)" "$1$1" dump.json >/dev/null` | **0.942 ± 0.004** | 0.936…0.951 |
Result: ~11.93 times faster
## Installation
### Cargo
[Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) is the Rust package manager.
You can install cargo by
```sh
curl https://sh.rustup.rs -sSf | sh
```
Then
```sh
cargo install sd
```
### Alpine Linux
```sh
apk add sd
```
Before installing, ensure the appropriate [repository](https://pkgs.alpinelinux.org/packages?name=sd) is enabled.
### Arch Linux
```sh
pacman -S sd
```
### Fedora
```sh
dnf install sd
```
### FreeBSD
```sh
pkg install sd
```
### Windows
```sh
choco install sd-cli
```
### macOS
```sh
brew install sd
```
### Void Linux
```sh
xbps-install sd
```
## Quick Guide
1. **String-literal mode**. By default, expressions are treated as regex. Use `-s` or `--string-mode` to disable regex.
```sh
> echo 'lots((([]))) of special chars' | sd -s '((([])))' ''
lots of special chars
```
2. **Basic regex use** - let's trim some trailing whitespace
```sh
> echo 'lorem ipsum 23 ' | sd '\s+$' ''
lorem ipsum 23
```
3. **Capture groups**
Indexed capture groups:
```sh
> echo 'cargo +nightly watch' | sd '(\w+)\s+\+(\w+)\s+(\w+)' 'cmd: $1, channel: $2, subcmd: $3'
cmd: cargo, channel: nightly, subcmd: watch
```
Named capture groups:
```sh
> echo "123.45" | sd '(?P<dollars>\d+)\.(?P<cents>\d+)' '$dollars dollars and $cents cents'
123 dollars and 45 cents
```
In the unlikely case you stumble upon ambiguities, resolve them by using `${var}` instead of `$var`. Here's an example:
```sh
> echo '123.45' | sd '(?P<dollars>\d+)\.(?P<cents>\d+)' '$dollars_dollars and $cents_cents'
and
> echo '123.45' | sd '(?P<dollars>\d+)\.(?P<cents>\d+)' '${dollars}_dollars and ${cents}_cents'
123_dollars and 45_cents
```
4. **Find & replace in a file**
```sh
> sd 'window.fetch' 'fetch' http.js
```
That's it. The file is modified in-place.
To preview changes:
```sh
> sd -p 'window.fetch' 'fetch' http.js
```
5. **Find & replace across project**
This example uses [fd](https://github.com/sharkdp/fd).
Good ol' unix philosophy to the rescue.
```sh
sd 'from "react"' 'from "preact"' $(fd --type file)
```
Same, but with backups (consider version control).
```bash
for file in $(fd --type file); do
cp "$file" "$file.bk"
sd 'from "react"' 'from "preact"' "$file";
done
```
### Edge cases
replace/-with string needs extra `--` before it, if starts with double-minus
(this is a limitation of the bash itself)
```bash
echo "test/test" | sd '/' -- '--inteneded--'
test--inteneded--test
echo "start/--/end" | sd --string-mode -- '--' 'middle'
start/middle/end
```
|
