Vim macros (or as the manual calls them, "Complex repeats") are used as a way to quickly enter and repeat a sequence of commands in Vim. They are lightweight and easier to pick up when compared to mappings or Vim scripts.
Macros live in registers, which are used to store text in Vim like a clipboard.
The difference is that when a macro is called via n, register
n's contents will be executed as input in Vim.
Manually creating a macro
If you were to yank the following text:
…and then enter @", Vim will insert the word "hello".
Running :reg (a command that lists all currently active registers)
will show that the register labelled
"" will match the contents of
Vim macros can be stored manually in a manner similar to this, or they can be recorded directly using the q command. (see :help complex-repeat.)
Recording keypresses to create a macro
Pressing q followed by the register identifier to record to (e.g.
qn to record to register
n) will tell Vim to remember every
keystroke pressed while in recording mode.
When q is pressed a second time, Vim will exit recording mode and the register will be updated to be a copy of every keypress that was made.
The command to create the
ihello macro from above by recording keypresses
Because macros live in registers, they can be edited on the fly in a convenient manner. Often is the case that I will finish recording a Vim macro only to realise I missed a step or need to add some final few steps.
There are two ways macros can modified:
- by appending to the macro; or
- by manually editing the macro.
Appending to a macro
To append to a macro, use the capitalised equivalent of the register you are
using. If the macro to append to exists on register
a, typing qA
will start Vim recording from where the
a macro left off.
For example, if the current
a macro is:
…then to append the word "hello" on the end, you could do the following:
This will result in :reg a showing
ihelloi world. The
hello is because Vim had to enter insert mode when recording
the actions to type
What this means is that when this macro is called, Vim will output
helloi world, because the first
i in the register will enter insert mode.
It is caveats like this that make editing macros manually easier and less prone to error.
Manually editing a macro
To manually edit a macro, think of it as editing any other string of text. The editing can take place on the command line, or within a buffer or new line on Vim.
Editing on the command line
To edit on the command line, use the
let command to overwrite the register
- enter the command line by first typing :let @a=' (do not press Enter to execute yet);
- press C-r + C-r + a to insert the contents of the register
ato the command line; and
- edit the macro as required, append a closing
letcommand and press Enter.
Editing within the buffer
Editing a macro on a buffer means pasting the current contents of register
modifying the text and then yanking the contents back to the same register:
- type "ap to paste the contents of register
- edit the contents as required; then
- type "a before a yank command to store the selected text into
Entering special characters
Keys like Esc and Enter can be very common in macros. When editing a macro manually, these characters have to be presented literally.
To type a character literally in Vim, press C-v followed by the desired key while in insert or command mode.
For example, to type the
^[ character (i.e. the Esc key) in Vim,
you will need to press C-v followed by C-[ or Esc in insert mode.
For a one-off use of a macro type the @ command to execute the
contents of a specified register. For register
a, type @a.
To run the most recently used macro, type @@.
To run a macro across all buffers, run the following in the command line:
:bufdo execute "normal @a" | write
The above is telling Vim to:
@ain Vim's normal mode; and then
- write the file.
execute is needed in this instance to write each buffer after
modification, or else Vim may error when applying a macro and switching to the
next buffer. The exact behaviour depends on if
autowrite has been enabled,
which controls how Vim handles unsaved changes when switching buffers.
This means that the command :bufdo normal @a will work if