22.2 The Keyboard Macro Ring

All defined keyboard macros are recorded in the “keyboard macro ring”, a list of sequences of keys. There is only one keyboard macro ring, shared by all buffers.

All commands which operate on the keyboard macro ring use the same C-x C-k prefix. Most of these commands can be executed and repeated immediately after each other without repeating the C-x C-k prefix. For example,

     C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d

will rotate the keyboard macro ring to the “second previous” macro, execute the resulting head macro three times, rotate back to the original head macro, execute that once, rotate to the “previous” macro, execute that, and finally delete it from the macro ring.

The command C-x C-k C-k (kmacro-end-or-call-macro-repeat) executes the keyboard macro at the head of the macro ring. You can repeat the macro immediately by typing another C-k, or you can rotate the macro ring immediately by typing C-n or C-p.

When a keyboard macro is being defined, C-x C-k C-k behaves like C-x ) except that, immediately afterward, you can use most key bindings of this section without the C-x C-k prefix. For instance, another C-k will re-execute the macro.

The commands C-x C-k C-n (kmacro-cycle-ring-next) and C-x C-k C-p (kmacro-cycle-ring-previous) rotate the macro ring, bringing the next or previous keyboard macro to the head of the macro ring. The definition of the new head macro is displayed in the echo area. You can continue to rotate the macro ring immediately by repeating just C-n and C-p until the desired macro is at the head of the ring. To execute the new macro ring head immediately, just type C-k.

Note that Emacs treats the head of the macro ring as the “last defined keyboard macro”. For instance, it is the keyboard macro that C-x e will execute.

The command C-x C-k C-v (kmacro-view-macro-repeat) displays the last keyboard macro, or when repeated (with C-v), it displays the previous macro on the macro ring, just like C-x C-k C-p, but without actually rotating the macro ring. If you enter C-k immediately after displaying a macro from the ring, that macro is executed, but still without altering the macro ring.

So while e.g. C-x C-k C-p C-p C-p C-k C-k makes the 3rd previous macro the current macro and executes it twice, C-x C-k C-v C-v C-v C-k C-k will display and execute the 3rd previous macro once and then the current macro once.

The command C-x C-k C-d (kmacro-delete-ring-head) removes and deletes the macro currently at the head of the macro ring. You can use this to delete a macro that didn't work as expected, or which you don't need anymore.

The command C-x C-k C-t (kmacro-swap-ring) interchanges the head of the macro ring with the previous element on the macro ring.

The command C-x C-k C-l (kmacro-call-ring-2nd-repeat) executes the previous (rather than the head) element on the macro ring.

The maximum number of macros stored in the keyboard macro ring is determined by the customizable variable kmacro-ring-max.