Neovim: Quick Start

Assuming the plugin is installed and gui = true.

Start a session

1. Open a file in your project.
2. Put the cursor on an executable line and run :ToggleBreakpoint (or press <leader>db).
3. Run :DebugStart.

The debugger window opens, the program runs and stops at your breakpoint. In Neovim, ▶ appears on the stop line and the line is highlighted.

If you do not set a breakpoint explicitly, the frontend uses the current line as the initial one.

No config yet? It still works

:DebugStart in a project without .bugsaur/config.toml does not fail. The debugger looks for a language marker, generates the config, says so, and carries on. The file lands in your repository and is then yours to edit.

When several candidates exist — a workspace with several binaries, Go with several cmd/*, Python with several entry points — all of them are written out, and default is set to the one whose file you started debugging from.

To create the config ahead of time, without launching anything:

bugsaur init
bugsaur init /path/to/project

If the language is not recognised, the launch stops with an error naming the directory. The debugger will not silently debug the wrong thing.

Pick a profile

:DebugStart worker

Profile names complete with Tab, read from the project config. With no argument, default is used.

Debug the test under the cursor

:DebugTest

by default <leader>dT. The cursor must be inside a test function — in Rust, #[test] also counts. On any other line the command refuses and starts nothing.

If the cursor is on a test group line — mod tests, for instance — the same command runs the whole group.

Two conditions people trip over

The buffer must be saved. The backend reads the file from disk and cannot reliably match unsaved text against a compiled binary.

Saved breakpoints are not picked up. Unlike :DebugStart, a test run uses only the breakpoints of that request.

Control execution

:DebugContinue
:DebugStepOver
:DebugStepInto
:DebugStepOut
:DebugPause
:DebugStop
:DebugFocus

The default mappings are <leader>dS (start), <leader>dT (debug the test under the cursor), <leader>dc, <leader>do, <leader>di, <leader>dO, <leader>dp, <leader>dt, <leader>du, <leader>db. Full list with descriptions: Keymaps.

Conditional breakpoints

:ToggleBreakpoint condition == value

The expression is in the debuggee's language, and the program stops only when it is true.

Closing Neovim does not end the session

The backend keeps running. Reconnecting gets the current state, so you can restart your editor mid-session without losing the debug session.

With auto_attach = true in setup(), starting Neovim silently reattaches to the project's running session.