[Lldb-commits] [lldb] [lldb] Add repeat commands documentation (PR #194923)

[David Spickett via lldb-commits]

================
@@ -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
----------------
DavidSpickett wrote:

I'm not sure what " and records the end of that region" means exactly, I guess you mean it shows the end. But I think you can just remove this part anyway. "displays the memory region containing that address." is fine combined with the example.

https://github.com/llvm/llvm-project/pull/194923