How GDB's Source-Tracking Breakpoints Save Your Debugging Sanity

Imagine you're deep in a debugging session, breakpoints set on specific lines, gathering clues. You make a code edit, recompile, and reload—only to find your breakpoints now point to the wrong lines because the line numbers shifted. Usually, you'd have to manually disable and reset them. GDB's experimental source-tracking breakpoints solve this by automatically adjusting breakpoints after code changes. This feature captures a snippet of the surrounding source when you set a breakpoint. When you recompile and reload, GDB searches for that snippet in the new binary and updates the breakpoint to its correct line. In this Q&A, we'll cover how to enable and use this feature, what happens behind the scenes, and its current limitations.

What exactly are source-tracking breakpoints in GDB?

Source-tracking breakpoints are an experimental feature of GDB (the GNU Project Debugger) that allow breakpoints set via file:line notation to survive code edits. Normally, if you change your source and recompile, breakpoint line numbers become outdated because lines may shift. This feature captures a small window of the source code around the breakpoint when it is set. After recompiling and reloading the executable, GDB searches the new binary's debug info for a matching snippet of those lines. If found, it automatically adjusts the breakpoint to the new line number. This means you can edit, recompile, and run again without manually resetting breakpoints—a huge time-saver during iterative debugging. The breakpoint stays associated with the same logical location in the source, even if the line number changes.

How do I enable and use source-tracking breakpoints?

To activate the feature, first run the following command in GDB:

(gdb) set breakpoint source-tracking enabled on

Then set a breakpoint using the standard file:line notation, for example:

(gdb) break myfile.c:42
Breakpoint 1 at 0x401234: file myfile.c, line 42.

GDB now stores a snippet of the source (typically a few lines around line 42). You can also verify that tracking is active by checking the output of info breakpoints. The breakpoint entry will show source-tracking enabled along with the number of lines being tracked. After you edit myfile.c—say inserting a few lines above line 42—recompile and reload the binary with the run command, GDB will automatically attempt to relocate the breakpoint. If successful, it prints a message like Breakpoint 1 adjusted from line 42 to line 45.

How does GDB automatically adjust breakpoints after code changes?

When you enable source-tracking and set a breakpoint, GDB captures a textual snippet of the source code around that breakpoint line—by default, three lines. This snippet is stored along with the breakpoint. After you recompile and reload the executable, GDB examines the new debug information. It looks for an exact match of that snippet within a limited search window (12 lines around the breakpoint's original line). If it finds a match, it updates the breakpoint's line number to the new location. The adjustment happens automatically when you issue the run command (or reload the binary). GDB then displays a confirmation that the breakpoint was moved. This process relies on the source lines being unchanged in content; only whitespace or minor formatting changes can confuse the matcher. The goal is to keep your breakpoint logically attached to the same code, even as line numbers shift due to edits elsewhere in the file.

What does the info breakpoints command show for tracked breakpoints?

When a breakpoint is source-tracked, the info breakpoints output includes an extra annotation indicating that the feature is enabled. For example:

(gdb) info breakpoints
Num     Type           Disp Enb Address            What
1       breakpoint     keep y   0x0000000000401234  in calculate at myfile.c:42
        source-tracking enabled (tracking 3 lines around line 42)

The first line shows the breakpoint number, type, disposition, enable status, address, and location. The second line (indented) shows source-tracking enabled and the number of source lines being tracked (usually 3). After an adjustment, you'll see the new line number reflected. For instance, after the breakpoint moves from line 42 to line 45, the info display will show at myfile.c:45 and still say tracking 3 lines around line 45. This gives you clear visibility into whether a breakpoint is being tracked and where it currently resides.

Are there any limitations I should know about?

Yes, source-tracking breakpoints have several limitations:

• Exact string match required: The captured snippet must match the new source exactly. Even trivial whitespace changes (like adding spaces) or reformatting of the tracked lines will confuse the matcher, causing the breakpoint not to be found.
• Limited search window: GDB only searches within a 12-line window around the original location. If your code shifts by more than 12 lines (e.g., because a large block was inserted above), the breakpoint will not be found.
• Pending breakpoints: Source context cannot be captured when a breakpoint is created pending (e.g., with set breakpoint pending on), because no symbol table is available yet. In such cases, tracking is disabled.

These limitations mean the feature works best for small edits near the breakpoint, not major restructuring.

What happens if the source code shifts beyond the search window?

If the code around the breakpoint has shifted by more than 12 lines from its original position, GDB will fail to locate the matching source snippet. In that case, it keeps the breakpoint at its original location (which is now wrong) and prints a warning message like:

warning: Breakpoint 1 source code not found after reload, keeping original location.

The breakpoint remains enabled but now points to an incorrect line. You'll need to manually disable or delete it and set a new breakpoint at the correct line. This scenario is common when large blocks of code are inserted above the breakpoint, or when the file is significantly restructured. To avoid this, try to set breakpoints on code that is unlikely to be moved far, or be prepared to reset them after major edits. The feature is designed for iterative small changes, not wholesale rewrites.

When does source-tracking fail to capture context?

Source-tracking cannot capture context when a breakpoint is created in a pending state. This occurs when you use the set breakpoint pending on setting, or when the symbol table is not yet loaded at the time the breakpoint is set (e.g., if the shared library hasn't been loaded). In such cases, GDB does not have access to the source lines to capture a snippet. The breakpoint will still be set, but it will not be source-tracked. When the pending breakpoint resolves later (after the library loads), no tracking information is added retroactively. Therefore, if you plan to rely on automatic adjustment, it's best to set breakpoints after all symbols are available, or ensure that pending breakpoints are set only when you don't need tracking. You can also disable pending breakpoints entirely if you prefer explicit tracking.