Breakpoints¶
A breakpoint tells the debugger where to stop. In Bugsaur they belong to the project, not to a session — and not to the debugger window.
Where breakpoints live¶
Breakpoints are stored in <root>/.bugsaur/breakpoints.json, next to the
project config. That file is written by the editor and read by the debugger, so:
- they survive an editor restart;
- they survive a debugger restart;
- the terminal debugger and Neovim see the same set.
The file is personal rather than shared: .bugsaur/.gitignore keeps it out of
version control.
Setting and clearing them¶
In Neovim:
on the current line. With an argument, the breakpoint becomes conditional — the program only stops when the expression is true, in the debuggee's own language.
From the command line, pass them at launch:
An explicit --break replaces the saved set entirely
Without --break, Bugsaur uses the set from .bugsaur/breakpoints.json.
With it, the saved set is not merged — the command line wins outright.
You cannot remove a breakpoint from the window¶
This is deliberate. The editor owns the breakpoint set of a file. A deletion made in the debugger window would live only until the next change in Neovim or the next restart — a control that silently undoes itself is worse than no control. Set and clear them in the editor.
The Breakpoints panel¶
Ctrl+B opens it. Breakpoints are shown as a flat list, one row each:
file:line on the left, the dimmed directory on the right. The directory is
relative to the project root, and when it does not fit, segments are dropped
from the front (…/gateway/library-basic) — the tail is what distinguishes
neighbouring rows. The full path is in the hover tooltip.
The circle on the left¶
The circle says what the adapter knows about that breakpoint:
| Circle | Meaning |
|---|---|
| Filled | the adapter confirmed it |
| Yellow ring | not confirmed — the line may not be executable |
| Dimmed ring | no answer yet |
A dimmed ring is normal for PHP: until Xdebug connects, the set is already visible in the window but there is nobody to ask about it.
Jumping to the source¶
Enter on the selected breakpoint — or a double click — asks the editor to open that file at that line. Execution does not move and no "we are here" marker is placed.
With no source frontend connected the request has nowhere to go, so in a window launched from a terminal it does nothing.
When a breakpoint does not fire¶
The single most common cause is a line that is not executable — a blank line, a comment, a declaration. The adapter then either moves the breakpoint to the next executable line or refuses to bind it, which is what the yellow ring reports.
Full decision tree: Troubleshooting → Breakpoints not hit.