I have found Vi / Vim macros extremely obtuse to understand even a week after I've written them. The syntax of a .vimrc file supports comments on lines beginning with a double-quote character (") and that helps. I can write paragraphs of notes to myself that way, but it would be really useful to be able to break up a macro definition to comment about each step of what it's doing.

Any ideas?

  • 1
    Welcome to Vi and Vim! Can you give an example macro? I can think of a way to use string concatenation on register-based macros, but key-mappings might be harder.
    – D. Ben Knoble
    Aug 29, 2020 at 13:21
  • I don't know the viability of this, but could you use a foo_macro variable? Then each following line would add part of the macro and could have a comment: let foo_macro+='$' " go to end of line. Then at the end have an nnoremap <expr> :exec 'normal! ' . foo_macro (substituting nnoremap for whatever mode you want)? Aug 29, 2020 at 17:23

2 Answers 2


A Vim macro is just text stored in a register, which is taken to represent normal mode commands.

Perhaps you could write commented Vimscript functions that constructed and returned a command string, like this:

func MakeMacro() 
    let l:m = ""
    " some comment
    let l:m .= "ifoo"
    " some other comment
    let l:m .= "\<Esc>"
    return l:m

After sourcing the function, you would assign its result to a Vim register:

:let @a=MakeMacro()

And invoke it in normal mode like a typical recorded macro:


See :h let (for the let @a syntax) and :h .=. See also :h expr-string for the syntax that allows including special keys like <Esc>.

  • Fantastic answer, welcome to Vi and Vim! This is what I was envisioning in my comment, though it doesn't work quite as well for the map family.
    – D. Ben Knoble
    Aug 31, 2020 at 2:48

Thanks @danidiaz and @Jake,

You both seem to be heading down similar paths and I had not even thought of doing it that way.

Here's what I came up with as a 2D .vimrc comment display format directly in the .vimrc file. Let me know what you think.

"= Yank the entire contents of the file into the clipboard; quit without saving.
"define F2 followed by y to be:
"|      Go to line 1.
"|      | From there, into the * buffer (system clipboard),
"|      | | yank to the end of the file.
"|      | | | Go to sleep for 1 second (to allow the clipboard to be updated).
"|      | | | |  Quit without saving the file.
"|      | | | |  |
map #2y 1G"*yG1gs:q!<CR>

I've flagged two lines above with "= at the beginning of each, so that they can become the User Help. Then a grep command could search for "^\"= ". Here's the command I used.

grep -B 1 -E "^\"= " ~/.vimrc

I'm not sure if the -E for Extended Regular Expressions is needed and I like the -B 1 to include one line previous to a matching sequence, so in the .vimrc fragment above, I have an explicitly empty comment line.

I can easily make a shell script for that and execute it with a ! command inside vim. I'm looking at how I might do that easily from inside vim, without the shell command, but that's a little lower priority.

Thanks again.

  • 2
    :nnoremap would be preferrable to :map, it avoids unexpected interactions . If we want to define a mapping that performs complex actions, at some point it pays to go the full route of: defining a function that performs the actions (possibly involving commands like :normal) then creating a command that invokes the function, finally creating a mapping that invokes the command. That process is described here: benjaminpetersen.com/vim-commands and here learnvimscriptthehardway.stevelosh.com. As for user help, perhaps the standard Vim help format could be used (:h help-writing)
    – danidiaz
    Aug 31, 2020 at 8:18
  • Re grep in vim... see :help :grep and :help :vim
    – D. Ben Knoble
    Aug 31, 2020 at 12:44

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.