User guide / Files and buffers

Shell pipes

Development reference · View source

:pipe <shell-command> (or :| <shell-command>) replaces each selection with the command’s output.

On Unix:

:pipe sort
:pipe tr a-z A-Z
:pipe jq .

How it works:

• Each selection is sent on stdin and replaced with stdout. Selected text is never inserted into the command, and editor variables are not expanded.
• Programs resolve through the inherited PATH.
• The working directory is the workspace root when the command starts.
• Stdout must be UTF-8 and is kept exactly, including trailing newlines. Empty stdout deletes the selection.
• All replacements are one undo step. Any failed invocation discards every replacement and reports an error.
• Commands can have side effects that undo and cancellation cannot reverse.

On Windows:

:pipe [Console]::Write([Console]::In.ReadToEnd().ToUpperInvariant())

• That example uppercases each selection.
• Console input, output, and native pipeline output are UTF-8 without a BOM.
• Use [Console]::In.ReadToEnd() and [Console]::Write(...) when exact newlines matter; PowerShell object pipelines format text their own way.
• The workspace directory needs an ordinary Windows spelling shorter than 260 UTF-16 units.

Limits:

Selections run one after another.

While it runs:

• Editing and rendering continue.
• The result goes to the buffer it came from, even after switching panes. It is refused if that buffer changed (including an edit then undo), closed, or became read-only. Moving selections does not retarget it.
• :pipe-cancel cancels the job.
• The workspace host owns the job in both modes, so detaching and reattaching does not restart or cancel it. Host shutdown cancels it.

Cleanup. Cancellation, timeout, failure, and completion kill the owned process tree.

• Unix uses a process group and reaps the shell. Processes that deliberately leave the group are outside its cleanup.
• Windows uses a job that forbids breakaway. Inherited output pipes cannot keep a finished shell’s job alive indefinitely.

There is no default key; the bare | key is reserved.