Text tools and the shell

Scope: what a command acts on

Every command in this lesson takes its scope from the : line, and the line shows it before you press Enter. Pressing : with a selection up prefills 'v, which means the selection itself, whatever shape it is.

Every command is one undo step and reports what it did.

Rearranging rows

:sort and its family work on whole rows: the file when nothing narrows them, otherwise the rows a range or selection touches.

deps.txt Sort, drop duplicates 1 / 3 play

1. start Ten dependencies, unsorted, two of them listed twice.
2. 1 :sort u No range means the whole file. u drops lines that compare equal.
3. 2 Enter Sorted as one undo step, and the report counts what went.

A range already in order reports already sorted and adds nothing to the undo history. :align only ever adds spaces, so running it twice changes nothing.

settings.lua Align on = 1 / 4 play

1. start A table whose values do not line up.
2. 1 V4j Select the five rows.
3. 2 : : with a selection up prefills 'v — the selection itself.
4. 3 align =Enter Spaces go before the first = on each row until they share a column.

Respelling names: :case

:case takes upper, lower, title, camel, pascal, snake, dash or const. With no scope it takes the word under each cursor, which is usually the thing you are renaming.

settings.lua Respell a name 1 / 4 play

1. start The cursor on maxRetryCount.
2. 1 :case snakeEnter No scope: the word under the cursor. max_retry_count.
3. 2 j:case snakeEnter An acronym is one word: HTTPTimeoutMs reads as http, timeout, ms.
4. 3 k:case constEnter Any spelling reads back into any other.

It respells every identifier in scope and leaves the text between them alone: foo_bar baz_qux in camel is fooBar bazQux. An acronym is one word (HTTPServer is http + server), a digit stays with its word, and a - b keeps its minus sign.

Encoding and decoding in place

A token in a header, a JSON blob in a log line: decode it where it sits, without the round trip through echo | base64 -d.

request.log Decode in place 1 / 5 play

1. start A request log: a base64 header and a JSON payload on one line.
2. 1 2WvE Select the base64 token.
3. 2 :base64dEnter : prefills 'v; base64d swaps the token for what it says.
4. 3 j0f{vg_ Select the JSON on the next line.
5. 4 :jsonfmtEnter Pretty-printed with this file’s indent, keys in their order.

With no scope these act on the whole file, so :jsonfmt formats a JSON file. Each contiguous piece is handled on its own: two selections are two blobs, and a rectangle is one blob per row. Input that does not decode — not base64, not UTF-8 underneath, not JSON — is an error naming the problem, and nothing changes, not even the pieces that did decode.

Generating values

Ids, dates and filler, typed for you. Each one goes after the cursor (the way p pastes) or replaces the selection, and every cursor gets its own.

fixtures.lua One id per cursor 1 / 4 play

1. start Three fixtures waiting for ids. The cursor is on the first opening quote.
2. 1 Ctrl-Alt-↓Ctrl-Alt-↓ Ctrl-Alt-Down twice: a cursor on each row, same column.
3. 2 :uuid4Enter An id goes after every cursor, and each cursor gets its own.
4. 3 u:ulidEnter Undo, then a ulid instead — time-ordered, 26 characters.

A line range such as :2,5uuid4 is refused: replacing four lines with one id is not a thing anyone means.

Shell commands

bi has four ! forms and they split into two kinds. Bare :!cmd is a job: it runs in the background and the editor stays live. With a range, ! is a filter: it runs synchronously, and its result becomes an edit.

Jobs

inventory.c Run a build 1 / 5 play

1. start A C file and its Makefile.
2. 1 :!make -B && ./inventory A bare :! runs a job in the background.
3. 2 Enter Output streams into a log buffer in a split below, and focus goes with it.
4. 3 Ctrl-Wp Ctrl-W p goes back to the file the job was run from.
5. 4 :lsEnter The log is a buffer like any other: the switcher lists it as [!make -B && ./inventory].

A job’s output streams into a transient buffer named [!cmd], opened in a split below with focus inside it. stderr lines are interleaved, prefixed ! , and colour codes are stripped. The status line shows ! exited 0, ! killed or ! signal when the job ends.

% expands to the current file’s path and # to the alternate file’s; \% and \# are the characters themselves — see the placeholders below. One job runs at a time, and its stdin is closed, so a program that prompts gets EOF instead of hanging.

The [!cmd] buffer is a real buffer — motions, search, yank, even :%!sort work in it — but it never asks to be saved, has no LSP or git signs, and keeps at most 10,000 lines. :w <path> writes a copy.

Filters

deps.txt Filter and read 1 / 4 play

1. start The same list of dependencies.
2. 1 :%!column -t A range makes ! a filter: the lines go in, stdout comes back in their place.
3. 2 Enter Replaced in one undo step. A failing command would have left the text alone.
4. 3 G:r !date +\%FEnter :r !cmd reads output in below the cursor. % means this file, so a literal one is \%.

Filters have a 5-second guard; anything that runs longer should be a job. If the command exits non-zero, the text is left alone and the status shows the first line of stderr.

File name placeholders

% and # are not only for :!. Every ex command that takes a path — :w, :wq, :e, :sp, :vs, :! — reads them, and a modifier after either picks the file apart. Modifiers chain, left to right.

# takes the same modifiers over the alternate file. So, editing assets/atlas.png:

:w %:r.normal.%:e        writes assets/atlas.normal.png
:w $dir/normal.png       writes assets/normal.png
:e %:r.json              opens assets/atlas.json
:vs #:r.rs               splits on the alternate's .rs neighbour
:!convert % %:r.jpg      the shell gets both names

The $ names are the same seven spellings under Ruby’s File vocabulary, and the two mix freely. \%, \# and \$ are the literal characters, and a $ that is not one of the six names is left alone — :!echo $HOME still asks the shell. The edges are vim’s: :r on a name with no extension changes nothing, :h on a bare name is ., and archive.tar.gz loses one extension per :r.

The current file is the focused window’s, whichever kind of window it is. A window with no file — an empty buffer, a tree — answers no file name for %.

Indentation: :retab

.editorconfig decides what bi inserts. It does not rewrite indentation that is already in the file. :retab does:

It rewrites only leading whitespace and preserves width: a tab drawn eight columns wide becomes eight spaces. It never runs on write, because a save should not turn a one-line fix into a whole-file diff.