Commit: runtime(doc): clarify :silent usage for system()/systemlist()

[Christian Brabandt]

runtime(doc): clarify :silent usage for system()/systemlist()

Commit: https://github.com/vim/vim/commit/751b59e539e80a0b35fb5c6d1b763a86bcac2304
Author: Yasuhiro Matsumoto <matt...@gmail.com>
Date: Sun Mar 15 09:16:42 2026 +0000

runtime(doc): clarify :silent usage for system()/systemlist()

When system() or systemlist() is called without :silent from a
statusline expression, autocommand, or timer callback, the terminal
is temporarily set to cooked mode, which re-enables ECHO on the tty.
If a terminal response (e.g. DECRPM for cursor blink mode) arrives
during this window, the tty driver echoes it to the screen, leaving
stray characters that require CTRL-L to remove.

This behavior was intentionally addressed in patch 7.4.427 by
skipping cooked mode when :silent is prepended. However, the
documentation only mentioned this for system() and did not cover
systemlist() at all. The guidance to use :silent in non-interactive
contexts (statusline, autocommands, timers) was also not explicit.

closes #19691

Signed-off-by: Yasuhiro Matsumoto <matt...@gmail.com>
Signed-off-by: Christian Brabandt <c...@256bit.org>

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 45072ab16..21dc56c33 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt* For Vim version 9.2. Last change: 2026 Mar 13
+*builtin.txt* For Vim version 9.2. Last change: 2026 Mar 15


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -11713,7 +11713,11 @@ system({expr} [, {input}]) *system()* *E677*
When prepended by |:silent| the terminal will not be set to
cooked mode. This is meant to be used for commands that do
not need the user to type. It avoids stray characters showing
- up on the screen which require |CTRL-L| to remove. >
+ up on the screen which require |CTRL-L| to remove.
+ When calling system() from a |statusline| expression, an
+ |autocommand| or a |timer| callback, you should use |:silent|
+ to avoid terminal responses (e.g. from cursor style queries)
+ being echoed on the screen. >
:silent let f = system('ls *.vim')
<
Note: Use |shellescape()| or |::S| with |expand()| or
@@ -11771,6 +11775,11 @@ systemlist({expr} [, {input}]) *systemlist()*
<
Returns an empty string on error.

+ Like |system()|, prepend |:silent| when the command does not
+ need user interaction and is called from a |statusline|
+ expression, an |autocommand| or a |timer| callback. See
+ |system()| for details.
+
Can also be used as a |method|: >
:echo GetCmd()->systemlist()
<