Macros

Tip 398 Printable Monobook Previous Next

created 2003 · complexity basic · author torelg · version 6.0

---

In Vim, the word "macro" may refer to:

• Commands recorded in a register.
• A mapping to expand a sequence of typed keys to a longer sequence.
• A script written in the Vim script language (stored in a file with extension .vim).

This tip is concerned with the first meaning (recording a command into a register).

There are often many ways to accomplish a task in Vim. Recording a macro is a great way to accomplish a one-time task, to get things done quickly when you don't want to mess with Vim script or mappings, or if you just plain don't know how to do it more elegantly (yet).

Recording a macro

Each register is identified by a letter a to z.

To enter a macro, type:

q<letter><commands>q

To execute the macro <number> times (once by default), type:

<number>@<letter>

---

qq # record to q

your complex series of commands

q

@q to execute

@@ to repeat

Quickly run a macro

Use this mapping as a convenient way to play a recorded macro:

:nnoremap <Space> @q

Start recording keystrokes by typing qq.

End recording with q (first press Escape if you're in insert mode).

Play the recorded keystrokes by hitting space.

Viewing macros

You can use the :registers command to view the current contents of any or all register values in Vim. For example, use :reg to view all the registers, or :reg a to view only what you have recorded into register 'a'.

Saving macros

There are two primary ways of saving a macro for later use.

The first way occurs by default if you run Vim in nocompatible mode (which is the default if you have a vimrc). Simply by including the proper text in your 'viminfo' option or leaving the nocompatible default alone, Vim will automatically write all your registers to a file and restore them at startup (within size limits, see :help 'viminfo').

The second way to save a macro for later use (especially if you think you might overwrite the macro by accident, therefore restoring the wrong value from the viminfo file) is to use a let command in your vimrc.

For a very simple example, suppose you have recorded a macro to jump to the first occurrence of the letter a in a line into register a, using the following key sequence in normal mode:

qa0faq

If you want to restore this macro whenever you start Vim, regardless of what might be in your viminfo file, you would edit your vimrc and add the following line:

let @a="0fa"

Assuming that you already have the macro recorded, you can easily insert the register contents rather that typing them all again. While entering the above line, after typing let @a=", simply type CTRL-R CTRL-R a to insert the contents of the 'a' register. The double CTRL-R is to insert the contents literally, rather than interpreting them as if typed.

By default, the contents of each register is saved, and will be available next time you run Vim. For example, you might record a macro to register a, then exit from Vim with :q!. On restarting Vim, you can press @a to run the macro from register a.

The 'viminfo' option can disable the saving of registers. If :set viminfo? shows a value including (for example) <50 and s10 then up to 50 lines and 10KB will be saved in each register. If either item is zero, no registers are saved. :help 'viminfo'

References

• :help registers
• :help recording
• :help :registers
• :help 'viminfo'
• :help i_CTRL-R_CTRL-R

Comments

 TO DO 

• Clean above, and add more content, with an example.
• Note that can edit a macro by changing register contents.
• Some relevant tips that perhaps should be referenced:
  • 170 Repeating a sequence of commands without defining a macro
  • 1577 Record a recursive macro
  • 45 Using command-line history (repeating commands without a macro)

---

:help has much more information in it than I would have imagined, especially discussion on scripts. We might also put pointers here to pulling up the individual help files. --Octopusgrabbus 13:38, 25 May 2009 (UTC)

If you feel so inclined, it's really easy to do this on our wiki! We have a help template that automatically links to the correct page in most circumstances. For example, just add {{help|'viminfo'}} to add a link as follows: :help 'viminfo'. --Fritzophrenic 02:42, 27 May 2009 (UTC)