diff options
author | Sean Whitton <spwhitton@spwhitton.name> | 2021-02-06 00:48:32 -0700 |
---|---|---|
committer | Sean Whitton <spwhitton@spwhitton.name> | 2021-12-24 14:08:06 -0700 |
commit | 98df5163018b9c99ad8e65f03422f908c6068c78 (patch) | |
tree | 5d43fd03c3df6fab042c926b146eed72eaed2fb8 /doc/misc/eshell.texi | |
parent | d47446cbe7db5c7fb4eba71ab022cfae3de07799 (diff) | |
download | emacs-series/unexpanded-input-v2.tar.gz |
Add eshell-shell-command and eshell-expand-to-eshell-shell-commandseries/unexpanded-input-v2
* lisp/eshell/esh-mode.el (eshell-shell-command,
eshell-expand-to-eshell-shell-command): Define new functions.
Register eshell-expand-to-eshell-shell-command as a customization
option for eshell-expand-input-functions, and add it by default.
* etc/NEWS:
* doc/misc/eshell.texi: Document the new syntax.
Diffstat (limited to 'doc/misc/eshell.texi')
-rw-r--r-- | doc/misc/eshell.texi | 35 |
1 files changed, 35 insertions, 0 deletions
diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index a87dd4308c5..7e9233c09e1 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -875,6 +875,7 @@ is equivalent to entering the value of @code{var} at the prompt.} @menu * Dollars Expansion:: * Globbing:: +* Running Shell Pipelines Natively:: @end menu @node Dollars Expansion @@ -945,6 +946,40 @@ Eshell see the Customize@footnote{@xref{Easy Customization, , , emacs, The GNU Emacs Manual}.} groups ``eshell-glob'' and ``eshell-pred''. +@node Running Shell Pipelines Natively +@section Running Shell Pipelines Natively +When constructing shell pipelines that will move a lot of data, it is +a good idea to bypass Eshell's own pipelining support and use the +operating system shell's instead. This is especially relevant when +executing commands on a remote machine using Eshell's Tramp +integration: using the remote shell's pipelining avoids copying the +data which will flow through the pipeline to local Emacs buffers and +then right back again. + +To quickly construct a command for the native shell, prefix your +Eshell input with the string @code{||}. For example, + +@example +|| cat *.ogg | my-cool-decoder >file +@end example + +Executing this command will not copy all the data in the *.ogg files +into Emacs buffers, as would normally happen with Eshell's own +pipelining. + +As this feature is implemented as an expansion, your original input +will be replaced with something like this: + +@example +eshell-shell-command \"cat *.ogg | my-cool-decoder >file\" +@end example + +This makes it clear what Eshell is doing, but has the disadvantage of +being harder to edit, especially for complex pipelines with a lot of +quoting. If you would prefer that the @code{||}-prefixed input be +restored, customize the variable @code{eshell-input-filter-functions} +to include the function @code{eshell-restore-unexpanded-input}. + @node Input/Output @chapter Input/Output Since Eshell does not communicate with a terminal like most command |