commit 1128d75550fa0b481b8953a194bae890d733a166
parent 1643c49514cef2ab6fafea1959d66503b0fb045e
Author: zeertzjq <zeertzjq@outlook.com>
Date: Wed, 13 Nov 2024 07:38:59 +0800
vim-patch:f18987c: runtime(doc): clarify the use of filters and external commands (#31185)
related: vim/vim#16044
https://github.com/vim/vim/commit/f18987caa5095e9ff154f924d952047c67c9fb64
Co-authored-by: Christian Brabandt <cb@256bit.org>
Diffstat:
3 files changed, 8 insertions(+), 0 deletions(-)
diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
@@ -561,6 +561,8 @@ with ".". Vim does not recognize a comment (starting with '"') after the
program {filter} (for {Visual} see |Visual-mode|).
:{range}![!]{filter} [!][arg] *:range!*
+ For executing external commands see |:!|
+
Filter {range} lines through the external program
{filter}. Vim replaces the optional bangs with the
latest given command and appends the optional [arg].
diff --git a/runtime/doc/usr_10.txt b/runtime/doc/usr_10.txt
@@ -736,6 +736,11 @@ The "!!" command filters the current line through a filter. In Unix the "date"
command prints the current time and date. "!!date<Enter>" replaces the current
line with the output of "date". This is useful to add a timestamp to a file.
+Note: There is a difference between "!cmd" (e.g. using it without any file
+range) and "{range}!cmd". While the former will simply execute the external
+command and Vim will show the output, the latter will filter {range}lines
+through the filter and replace that range by the result of the filter command.
+See |:!| and |:range!| for details.
WHEN IT DOESN'T WORK
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
@@ -267,6 +267,7 @@ gx Opens the current filepath or URL (decided by
<
*:!cmd* *:!*
:!{cmd} Execute {cmd} with 'shell'. See also |:terminal|.
+ For the filter command, see |:range!|.
The command runs in a non-interactive shell connected
to a pipe (not a terminal). Use |:terminal| to run an
