How do I set breakpoints and debug Vimscript functions interactively?

Explanation

Vim has a built-in debugger for Vimscript that most users never discover. The :breakadd command sets breakpoints on functions, files, or specific line numbers, then drops you into an interactive debug prompt when execution hits that point. This is invaluable when troubleshooting misbehaving autocommands, plugin functions, or complex vimrc logic.

How it works

• :breakadd func {funcname} — sets a breakpoint at the start of a function
• :breakadd file {filename} — breaks when a script file is sourced
• :breakadd here — sets a breakpoint at the current line of the current script

When a breakpoint is hit, Vim enters debug mode with these commands:

• cont — continue execution until the next breakpoint
• next — execute the next command (step over)
• step — step into function calls
• finish — finish the current function and break in the caller
• quit — abort the current script

Example

Debug a function that formats text incorrectly:

:breakadd func MyFormatFunction
:call MyFormatFunction()

Vim pauses at the first line of the function:

Breakpoint in "MyFormatFunction" line 1
function MyFormatFunction
line 1: let l:text = getline('.')
>cont

List and remove breakpoints:

:breaklist
:breakdel *

Tips

• Use :debug {cmd} to single-step through any command from the start without setting breakpoints
• Combine with :echo and :echomsg to inspect variable values at breakpoints
• Remove all breakpoints at once with :breakdel *