[Lldb-commits] [lldb] [lldb] Add repeat commands documentation (PR #194923)
Dave Lee via lldb-commits
lldb-commits at lists.llvm.org
Thu Apr 30 14:47:37 PDT 2026
https://github.com/kastiglione updated https://github.com/llvm/llvm-project/pull/194923
>From e32dbbc690a6cc9000f8f998db163cc8f5f6fc47 Mon Sep 17 00:00:00 2001
From: Dave Lee <davelee.com at gmail.com>
Date: Wed, 29 Apr 2026 10:50:17 -0700
Subject: [PATCH 1/2] [lldb] Add repeat commands documentation
---
lldb/docs/index.rst | 1 +
lldb/docs/use/repeat-commands.rst | 147 ++++++++++++++++++++++++++++++
2 files changed, 148 insertions(+)
create mode 100644 lldb/docs/use/repeat-commands.rst
diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst
index e124bfaf592d4..d8886aeef26ec 100644
--- a/lldb/docs/index.rst
+++ b/lldb/docs/index.rst
@@ -139,6 +139,7 @@ interesting areas to contribute to lldb.
use/variable
use/formatting
+ use/repeat-commands
use/symbolication
use/symbols
use/ondemand
diff --git a/lldb/docs/use/repeat-commands.rst b/lldb/docs/use/repeat-commands.rst
new file mode 100644
index 0000000000000..854faacc37447
--- /dev/null
+++ b/lldb/docs/use/repeat-commands.rst
@@ -0,0 +1,147 @@
+Repeat Commands
+===============
+
+In LLDB's command line interface, pressing Enter (an empty command) repeats the
+previous command. By default, the exact same command is re-executed. However,
+several commands customize this behavior to implement paging or progressive
+expansion, making it easy to explore data incrementally by pressing Enter
+repeatedly.
+
+This page documents the commands with custom repeat behavior.
+
+``thread backtrace`` (``bt``)
+-----------------------------
+
+When ``thread backtrace`` is invoked with the ``--count`` (``-c``) option, the
+repeat command pages through the backtrace by advancing the ``--start`` (``-s``)
+option by the count each time.
+
+For example:
+
+::
+
+ (lldb) bt 5
+ * thread #1, stop reason = breakpoint 1.1
+ * frame #0: handle_request at server.cpp:50
+ frame #1: parse_headers at http.cpp:12
+ frame #2: read_socket at socket.cpp:30
+ frame #3: accept_connection at listener.cpp:8
+ frame #4: event_loop at reactor.cpp:100
+ (lldb)
+ # repeats as: thread backtrace -c 5 -s 5
+ * thread #1, stop reason = breakpoint 1.1
+ frame #5: start_server at main.cpp:42
+ frame #6: load_config at config.cpp:7
+ ...
+ (lldb)
+ # repeats as: thread backtrace -c 5 -s 10
+
+Each press of Enter shows the next 5 frames. If ``--count`` is not specified,
+the full backtrace is displayed and there is no repeat command.
+
+``source list`` (``list``)
+--------------------------
+
+When ``source list`` is repeated, it shows the next block of source lines,
+continuing from where the previous listing ended. This mimics paging behavior.
+
+If the ``--reverse`` (``-r``) option was given, the repeat command continues
+listing in reverse (showing earlier source lines).
+
+::
+
+ (lldb) list # shows source around the current location
+ (lldb) # shows the next block of source lines
+ (lldb) # shows the next block after that
+
+ (lldb) list -r # shows source in reverse
+ (lldb) # continues listing in reverse
+
+``memory read``
+---------------
+
+When ``memory read`` is repeated, it continues reading from where the previous
+read ended. The repeat command drops the address arguments and re-uses the same
+format, size, and count options from the previous invocation.
+
+::
+
+ (lldb) memory read 0x1000 -c 32
+ 0x1000: 48 8b 05 a9 3b 00 00 48 ...
+ (lldb) # continues reading the next 32 bytes from 0x1020
+ (lldb) # continues reading from 0x1040
+
+``memory region``
+-----------------
+
+When ``memory region`` is given an address, it displays the memory region
+containing that address and records the end of that region. Pressing Enter then
+shows the next memory region, and so on, allowing you to walk through the
+process's entire memory map.
+
+::
+
+ (lldb) memory region 0x1000
+ [0x0000-0x2000) rw-
+ (lldb) # shows the next region starting at 0x2000
+ (lldb) # shows the next region after that
+
+``frame variable`` (``v``)
+--------------------------
+
+When ``frame variable`` is repeated, it re-runs the command with an incremented
+``--depth`` (``-D``) value. This progressively reveals deeper levels of nested
+data structures with each press of Enter.
+
+If no ``--depth`` option was specified in the original command, the repeat
+starts at one level beyond the target's default ``max-children-depth`` setting
+(default: 5). If ``--depth`` was specified, it increments the given value by 1
+each time.
+
+Consider a deeply nested configuration structure:
+
+::
+
+ (lldb) v config
+ (Config) config = {
+ server = {
+ network = {
+ tls = {
+ certificate = {
+ issuer = {...}
+ }
+ }
+ }
+ }
+ }
+ (lldb) # repeats as: frame variable --depth 6 config
+ (Config) config = {
+ server = {
+ network = {
+ tls = {
+ certificate = {
+ issuer = {
+ name = {...}
+ }
+ }
+ }
+ }
+ }
+ }
+ (lldb) # repeats as: frame variable --depth 7 config
+
+With the default ``max-children-depth`` of 5, the first output truncates at
+``issuer``. Each press of Enter reveals one more level without having to
+manually specify ``--depth``.
+
+``thread trace dump instructions``
+----------------------------------
+
+When repeated, this command adds the ``--continue`` flag, which continues
+dumping traced instructions from where the previous instruction dump left off.
+
+::
+
+ (lldb) thread trace dump instructions
+ ... first 20 instructions ...
+ (lldb) # continues dumping the next 20 instructions
>From de7a4b79a43c61e114a7c7ff5707126d5676e32d Mon Sep 17 00:00:00 2001
From: Dave Lee <davelee.com at gmail.com>
Date: Thu, 30 Apr 2026 14:47:14 -0700
Subject: [PATCH 2/2] Review feedback updates
---
lldb/docs/use/repeat-commands.rst | 22 ++++++++++++----------
1 file changed, 12 insertions(+), 10 deletions(-)
diff --git a/lldb/docs/use/repeat-commands.rst b/lldb/docs/use/repeat-commands.rst
index 854faacc37447..caa1afa577179 100644
--- a/lldb/docs/use/repeat-commands.rst
+++ b/lldb/docs/use/repeat-commands.rst
@@ -5,7 +5,11 @@ In LLDB's command line interface, pressing Enter (an empty command) repeats the
previous command. By default, the exact same command is re-executed. However,
several commands customize this behavior to implement paging or progressive
expansion, making it easy to explore data incrementally by pressing Enter
-repeatedly.
+repeatedly. Repeat commands can be learned and discovered by pressing enter and
+observing the result.
+
+In some instances, commands disable repeat commands, to prevent
+accidentally triggering a destructive operation (e.g. ``process launch``).
This page documents the commands with custom repeat behavior.
@@ -75,9 +79,8 @@ format, size, and count options from the previous invocation.
-----------------
When ``memory region`` is given an address, it displays the memory region
-containing that address and records the end of that region. Pressing Enter then
-shows the next memory region, and so on, allowing you to walk through the
-process's entire memory map.
+containing that address. Pressing Enter then shows the next memory region, and
+so on, allowing you to walk through the process's entire memory map.
::
@@ -93,10 +96,9 @@ When ``frame variable`` is repeated, it re-runs the command with an incremented
``--depth`` (``-D``) value. This progressively reveals deeper levels of nested
data structures with each press of Enter.
-If no ``--depth`` option was specified in the original command, the repeat
-starts at one level beyond the target's default ``max-children-depth`` setting
-(default: 5). If ``--depth`` was specified, it increments the given value by 1
-each time.
+If no ``--depth`` option was specified in the original command, the next repeat
+starts at one level beyond the ``target.max-children-depth`` default setting. If
+``--depth`` was specified, it increments the given value by 1 each time.
Consider a deeply nested configuration structure:
@@ -130,7 +132,7 @@ Consider a deeply nested configuration structure:
}
(lldb) # repeats as: frame variable --depth 7 config
-With the default ``max-children-depth`` of 5, the first output truncates at
+The default ``target.max-children-depth`` causes the first output to truncate at
``issuer``. Each press of Enter reveals one more level without having to
manually specify ``--depth``.
@@ -143,5 +145,5 @@ dumping traced instructions from where the previous instruction dump left off.
::
(lldb) thread trace dump instructions
- ... first 20 instructions ...
+ ... first batch of instructions ...
(lldb) # continues dumping the next 20 instructions
More information about the lldb-commits
mailing list