Search and replace

/ finds something in the file and s jumps to something on screen. This lesson is about changing text in bulk: in a few lines, on every matching line, and across every file in the project.

:s — substitute

:[range]s/{pattern}/{replacement}/[flags]

lstring.c :s over a range 1 / 5 play

1. start luaS_resize in lstring.c. Its parameter nsize is on lines 95 to 113.
2. 1 :95,113s/nsize/new_size/g A range, a literal pattern, a replacement, and g for every match on a line.
3. 2 Enter One command, one undo step. The report counts substitutions and lines; the cursor lands on the last line changed.
4. 3 u u takes the whole thing back.
5. 4 :%s/osize/x/gnEnter n counts the matches and changes nothing.

No range means the cursor’s line, which is why % is the most typed character in the command. The whole command is one undo step, the cursor lands on the last line changed, and the pattern becomes the last search, so n walks what you just replaced. Nothing matched is an error, not a silent no-op.

Without i or I it is smartcase, exactly like /: all lowercase ignores case, one capital makes it exact. Inside the pattern and the replacement, \ before the delimiter is the delimiter and \\ is a backslash — nothing else is an escape. The closing delimiter is optional: :%s/old/new works.

Doing it again

Ranges

Every command that takes lines — :s, :g, :d, :m, :sort, :normal — reads the same small address language.

Two addresses make a range: :10,20s/a/b/g, :.,$d, :.,.+5normal A;. Pressing : in visual mode prefills 'v. A line that does not exist is refused (no line 99), not clamped.

:g — a command on every matching line

lstring.c :g and :normal 1 / 5 play

1. start The same function. Three of its lines call tablerehash.
2. 1 :95,113g/tablerehash/normal A // rehash :g marks every line in the range that contains the pattern, then runs a command on each.
3. 2 Enter :normal replays the keys on every marked line — A then the text. Esc is pressed for you.
4. 3 u:95,113v/nsize/dEnter Undo, then :v: delete every line in the range that does not mention nsize.
5. 4 u Each :g was one undo step.

:g/pattern/cmd scans first — every line containing the pattern is marked — then runs the command on each, top to bottom. Nothing chases its own output, and the whole run is one undo step. :v (or :g!) takes the lines that do not match. With no range, :g scans the whole file.

The command after :g is one of d, s, &, m, case, retab or normal — anything else is refused by name. That whitelist is what keeps :g/x/q from closing the editor on the first match.

:normal {keys} replays keys as if typed, once per line under a range, and presses Esc for you at the end. It uses bi’s own keymap, not your remaps (vim’s :normal!), and takes raw characters — there is no <Esc> notation inside it yet.

:find — search the project

lstring.c :find across the project 1 / 6 play

1. start lstring.c, somewhere in the Lua sources.
2. 1 :find luaS_newlstr The whole argument is the pattern — literal, smart case.
3. 2 Enter Results fill a pane in this window: a heading per file, a row per matching line.
4. 3 jjjj j and k walk the rows.
5. 4 Enter Enter opens the file at the match’s column.
6. 5 Ctrl-^ Ctrl-^ swaps the pane back, as you left it.

:find walks every file under the project root — skipping what .gitignore ignores and binary files — and puts the matches in a results pane: one heading per file, one row per matching line.

:find needle           literal, smart case
:find src/ needle      only under src/
:find~ \bfn \w+        the pattern as a regular expression
:results               bring the last results pane back

The whole argument is the pattern, so :find fn main() searches for exactly that. A first word ending in / that names a real directory is a scope.

The pane is not an overlay: it stays open beside what you are editing, survives Enter, and :results brings back the last list with its prunes intact.

:replace — preview, prune, apply

lstring.c :replace with a preview 1 / 5 play

1. start Rename luaS_newlstr everywhere — but look first.
2. 1 :replace /luaS_newlstr/luaS_newstring/Enter Nothing is rewritten. The pane is armed: every row shows its line as it will read.
3. 2 jjx x drops a row you do not want changed.
4. 3 ja a applies the selected row, into its buffer, and marks it ✓. On a heading it applies the whole file.
5. 4 A A applies every row still pending. The files are modified buffers now — :wa writes them, u in any one takes it back.

:replace /old/new/     find old, preview replacing it with new
:replace //new/        preview rewriting what the focused pane shows
:replace~ /f(\w+)/$1/  regex, with $1 for the first group

:replace never rewrites on Enter. It arms the results pane: the title reads replace: old → new and every row shows its line as it will read. Then:

Applied rewrites go into buffers, never straight to disk. Each file is opened, edited as one undo step and left modified: :wa writes the lot, u in any one file takes that file back. A line that changed since the search is skipped and counted rather than rewritten.

A row is a line, so a line with the pattern twice is rewritten twice.