Creating, editing and using macros in Vim

Creating macros

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:

ihello

…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 ihello.

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 would be:

qaihello^[q

Editing macros

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:

  1. by appending to the macro; or
  2. 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:

ihello

…then to append the word "world" on the end of the macro's output, use the command:

qAi world

This will result in :reg a showing ihelloi world. The i character after hello is because Vim had to enter insert mode when recording the actions to type world.

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 contents:

  1. enter the command line by first typing :let @a=' (do not press Enter to execute yet);
  2. press C-r + C-r + a to insert the contents of the register a to the command line; and
  3. edit the macro as required, append a closing ' to the let command and press Enter.

Editing within the buffer

Editing a macro on a buffer means pasting the current contents of register a, modifying the text and then yanking the contents back to the same register:

  1. type "ap to paste the contents of register a;
  2. edit the contents as required; then
  3. type "a before a yank command to store the selected text into register a.

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.

Using macros

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:

  1. execute @a in Vim's normal mode; and then
  2. write the file.

The 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 autowrite is enabled.