runtime(doc): clarify :silent usage for system()/systemlist()
Commit:
https://github.com/vim/vim/commit/751b59e539e80a0b35fb5c6d1b763a86bcac2304
Author: Yasuhiro Matsumoto <[email protected]>
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 <[email protected]>
Signed-off-by: Christian Brabandt <[email protected]>
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()
<
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/vim_dev/E1w1hnP-006NJE-OF%40256bit.org.
