How can I debug issues in VimL?

Question

I'd like to know more about debugging in vim. What features does vim have that can help me to diagnose a problem I might have?

I'd basically like to know:

• How can I diagnose a problem with my .vimrc and other configuration files?
• What are some strategies to debugging a script in VimL?

Answer 1

How can I diagnose a problem with .vimrc and other configuration files?

If you're having some unexpected behavior in vim and you're not sure where the problem is originating, there are a few approaches to honing in on the source of the issue. One of the best first steps is to find out if your problem is normal vim behavior, caused by a plugin or caused by your .vimrc.

If your vim instance is setting a particular 'option' and you're not sure where it is being set. You can use the :verbose command to find out. For instance

:verbose set nocompatible?
nocompatible
     Last set from ~/.vimrc

To run an instance of vim without any plugins or configuration files run

vim -N -u NONE

I set this as to alias called cleanvim in my .bashrc file. The -u NONE is what's doing the magic here. The -N simply puts vim into nocompatible mode, which generally is desired. You can also use the option NORC to only exclude your vimrc. Note that if you use something like pathogen or vundle to instantiate your plugins from within your vimrc, then your plugins will also not load properly.

If you are using a plugin manager like pathogen or vundle then excluding your plugins is simple; just comment out the line in your .vimrc that calls pathogen or vundle. However if you have other plugins loaded from your .vim directory you can exclude them with the --noplugin flag.

If your problem is being caused by a plugin, try adding back plugins one by one to determine which one is causing the issue. From there you can either report the bug to the plugin's maintainer or try to diagnose the problem yourself using the tips from the rest of this answer.

If your problem is caused by your .vimrc there are some ways to hone in on the problem further. Once simple method is to add the finish command at some point in your .vimrc. Once this command is encountered the script will stop being sourced and no commands after it will be executed. In this way you can exclude large portions of your .vimrc and try to find out the general region where the problem is coming from.

What are some strategies to debugging a script in VimL?

Vim has a help section on this topic at :h debug-scripts. This describes vim's debug mode in detail, which will allow you to set breakpoints and step through a sourced file or user function. You can add a breakpoint on a specific function or a specific line in a file. For instance...

" set a breakpoint on the function MyCoolFunc
:breakadd func MyCoolFunc

" set a breakpoint on line 43 of your .vimrc
:breakadd file 43 .vimrc

" set a breakpoint at this location
:breakadd here

After you set a breakpoint you can source the file again to begin debug mode at that line. If you'd like to use debug mode on an entire file start vim with the -D flag. You could also run debug mode on a particular command. For example, say you're having trouble with a particular command :MyCommand. You can start debugging mode on this command with :debug MyCommand.

Once debug mode has been started you can use the usual set of vim commands. This is useful because you can now check the value of variables using the echo command to try and diagnose an issue. You can also use the verbose option to provide extra information about the following lines. See :h 'verbose' for its options.