Skip to content

Commit 751b59e

Browse files
mattnchrisbra
authored andcommitted
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]>
1 parent a8052af commit 751b59e

1 file changed

Lines changed: 11 additions & 2 deletions

File tree

‎runtime/doc/builtin.txt‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
*builtin.txt* For Vim version 9.2. Last change: 2026 Mar 13
1+
*builtin.txt* For Vim version 9.2. Last change: 2026 Mar 15
22

33

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

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

0 commit comments

Comments
 (0)