Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท Registers, Macros and Search

Vim Macros: Record, Replay and Edit Edits

Record keystrokes with q, replay them with @ and @@, run a macro on many lines with counts and :normal, write recursive macros, and fix a macro as text.

When the same edit has to happen on many lines and the dot command is not enough, you record a macro: a sequence of keystrokes saved in a register and replayed on demand. Macros are Vim's answer to "I need a small script for this one job".

Record, stop, replay

  1. q followed by a register letter starts recording into that register: qa records into register a. The status line shows recording @a.
  2. Perform your edits.
  3. Press q again to stop.
  4. @a replays macro a; @@ repeats the last macro; 5@a replays it five times.

Replay is always from the cursor position at that time, so a good macro starts from a known place and ends ready for the next run. That means normalizing at the start (0 or ^) and finishing with a motion to the next target, usually j.

A first example

You have a list of names, one per line, and want each wrapped in quotes with a trailing comma:

TEXT
alice
bob
carol

Record on the first line:

  • qa start recording into a
  • I"<Esc> insert a quote at the start
  • A",<Esc> append quote and comma at the end
  • j move to the next line, so the macro is ready for the next one
  • q stop

Now 2@a runs it on the remaining two lines. A larger list: 100@a. When it reaches the last line j fails, and a failing motion aborts the macro. That feature means 100@a safely stops at the end of the file rather than looping forever.

JS Macro replay model (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice the third line: the macro does its edits and then j fails on the last line. In real Vim the final line is already edited, and the abort stops the remaining repeats cleanly.

Macros are registers

A macro is just text in a register, so you can inspect and fix it:

  • :reg a shows the recorded keys; special keys appear as ^[ for Esc and ^M for Enter.
  • Paste it with "ap into a scratch buffer, edit the line, then yank it back with 0"ay$ (go to the line start, then yank to the end of the line into a).
  • :let @a = 'I"^[A",^[j' assigns a macro; type ^[ with Ctrl-v Esc in Insert mode.
  • Append more keystrokes to an existing macro by recording into the capital register: qA...q.

This "edit as text" approach is how you correct a mistake without re-recording everything.

Running a macro on many lines

Beyond 100@a, there are neat tools:

  • Visual range: select lines and run :'<,'>normal @a to run the macro on every selected line (each starting at its first column).
  • All lines: :%normal @a runs it on every line of the file.
  • Matching lines: :g/TODO/normal @a runs it only on lines containing TODO (the global command comes next).
  • Count on the key: 5@a repeats the replay five times, stopping early on failure.

With :normal the macro should not rely on j to move to the next line, because the command already supplies the line. Make the macro self-contained: edit the current line only.

Recursive macros

A macro that calls itself at its end keeps going until something fails, a pattern for "do this to every match in the file".

  1. Clear the register first with qaq so a recursive call is not run on the first pass.
  2. qa ... do the edit ... n (next match) ... @a ... q.
  3. Run @a. It runs until n fails with no more matches.

For example to change every colour to color: /colour<Enter>, qa, cwcolor<Esc>, n, @a, q, @a (clear the register before recording!). Since the dot command with n. does this particular job in two keys, reach for a recursive macro when the edit has several steps.

JS Recursive macro until failure (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Good macro habits

  • Start in a known state: begin with 0, ^ or a search, never assume the cursor column.
  • Prefer searches and text objects over counts: f, and ci" keep working when lines differ in length, unlike 5l.
  • End by moving to the next target so N@a works.
  • Test on one line, then run on two, then run on all. Undo with u if it surprises you (an entire macro run is several undo steps; u reverts one command at a time or use :earlier).
  • Keep a few macros in your config: store let @q = '...' in your vimrc for ones you reuse.

Macros and the dot command

Use . when the edit is a single change. Use a macro when it has several steps, includes navigation between changes, or needs a recursive loop. Both can combine: record a macro that includes dot-repeats.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you start recording a macro into register b?

    q followed by a register letter starts recording; q alone stops.
  2. 2. What happens when a motion inside a macro fails, for example j on the last line?

    A failing command aborts the macro, so 100@a safely stops at the end of the file.
  3. 3. How do you run macro a on every line of a file?

    :%normal runs a Normal-mode command on each line of the range.
  4. 4. How can you fix a mistake in a recorded macro?

    Registers are text, so you can paste with "ap, edit and yank with "ay$ or assign with :let.

Summary

  • qa ... q records into register a; @a, @@ and N@a replay.
  • Design macros to start from a known state and end on the next target.
  • A failing command aborts the macro, so large counts are safe.
  • Run macros on ranges with :normal @a and combine with :g.
  • Macros are register text: edit them with "ap, :let @a= or append with qA.

Next: Searching in Vim: Patterns, Offsets and Highlights