How to record and replay macros in Vim
qaq@a@@Press qa to start recording, make your edit, press q to stop, then press @a to replay it.
@@ replays the last macro again, and a count in front replays it that many times, so 5@a runs it five times. Recording makes the first edit, so replay it only for the places that are left.
A macro is just the keys you typed, kept in register a. It can hold several changes and the moves between them, which the dot can't repeat.
Worked example
Turn each word into a quoted string with a comma after it. The cursor starts on apple.
I and A find the start and end of any line, so the macro works on words of any length. It ends with j, so each replay starts on the next line. Recording changed apple, and 2@a does the other two.
Commands
- qa…q
- Record your keys into register
a. The edits happen as you record. - @a
- Replay the macro in register
a. - @@
- Replay the last macro again.
- 5@a
- Replay it five times.
- u
- Undo a whole replay. After 2@a, one u undoes both.
Start from a known place, end ready for the next
A replay starts wherever the cursor is. So begin the recording with a key that always lands in the same spot, like 0 for the start of the line, ^ for its first character, or a search. Then end it where the next replay should begin, usually with j to go down a line.
- 0
- Start at the beginning of the line, whatever column j left you in.
- ^
- Start at the first character that isn't a space, for indented lines.
- /TODO
- Start at the next match, however far away it is.
Let a failed move end the replay
A replay stops as soon as a motion or a search inside it fails. So you can give a bigger count than you need, like 99@a, and the macro stops by itself when it runs out of lines or matches.
- 99@a
- On the last line j can't go down, so the replay stops there.
- /draft
- When no match is left the search fails, so the replay stops there too.
Look at a macro and change it
A macro is plain text in its register. "ap puts it in the file, so you can read what you recorded. Fix it like any other text, then go to the start of the line and copy it back with "ay$.
- "ap
- Put the keys in
aas text. - 0"ay$
- Copy the edited line back into
a, without its line break.
When the dot is enough
If each place needs only one change, you don't need a macro. Make the change once, move, and press ., as the guide to repeating changes shows. Record a macro when each place needs two changes or more, because the dot repeats only the last one.
- .
- Repeat one change. Here that's all each line needs.
- j.
- After two changes, the dot repeats only the second.
Exceptions
- Recording into a register replaces what it held. If
ahas text you still need, record into another letter, like qb. - In Insert mode, q types a
q. Press Esc first, then q to stop recording. - A count inside the macro and a count before @a multiply. A macro that runs 2x, replayed with 3@a, deletes six characters.
- Without a key like 0 at the start, a replay begins in whatever column j left you, and the edit lands in the wrong place.
- Recording with a capital letter, like qA, adds keys to the end of macro
ainstead of recording over it. - "add also copies a macro back, but it takes the line break with it. A replay plays that as a move to the next line.