1 \input texinfo @c -*-texinfo-*-
3 @setfilename ../../info/eshell.info
4 @settitle Eshell: The Emacs Shell
11 This manual is for Eshell, the Emacs shell.
13 Copyright @copyright{} 1999--2016 Free Software Foundation, Inc.
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
20 and with the Back-Cover Texts as in (a) below. A copy of the license
21 is included in the section entitled ``GNU Free Documentation License''.
23 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
24 modify this GNU manual.''
28 @dircategory Emacs misc features
30 * Eshell: (eshell). A command shell implemented in Emacs Lisp.
35 @c The title is printed in a large font.
36 @center @titlefont{User's Guide}
38 @center @titlefont{to}
40 @center @titlefont{Eshell: The Emacs Shell}
47 @center John Wiegley & Aidan Gauland
51 @vskip 0pt plus 1filll
57 @c ================================================================
58 @c The real text starts here
59 @c ================================================================
65 Eshell is a shell-like command interpreter implemented in Emacs Lisp.
66 It invokes no external processes except for those requested by the
67 user. It is intended to be an alternative to the IELM (@pxref{Lisp Interaction, Emacs Lisp Interaction, , emacs, The Emacs Editor})
68 REPL for Emacs @emph{and} with an interface similar to command shells
69 such as @command{bash}, @command{zsh}, @command{rc}, or
71 @c This manual is updated to release 2.4 of Eshell.
77 * Introduction:: A brief introduction to the Emacs Shell.
82 * Bugs and ideas:: Known problems, and future ideas.
83 * GNU Free Documentation License:: The license for this documentation.
85 * Function and Variable Index::
94 @section What is Eshell?
95 @cindex what is Eshell?
96 @cindex Eshell, what it is
98 Eshell is a @dfn{command shell} written in Emacs Lisp. Everything it
99 does, it uses Emacs's facilities to do. This means that Eshell is as
100 portable as Emacs itself. It also means that cooperation with Lisp code
101 is natural and seamless.
103 What is a command shell? To properly understand the role of a shell,
104 it's necessary to visualize what a computer does for you. Basically, a
105 computer is a tool; in order to use that tool, you must tell it what to
106 do---or give it ``commands.'' These commands take many forms, such as
107 clicking with a mouse on certain parts of the screen. But that is only
108 one form of command input.
110 By far the most versatile way to express what you want the computer to
111 do is by using an abbreviated language called @dfn{script}. In
112 script, instead of telling the computer, ``list my files, please'',
113 one writes a standard abbreviated command word---@samp{ls}. Typing
114 @samp{ls} in a command shell is a script way of telling the computer
115 to list your files.@footnote{This is comparable to viewing the
116 contents of a folder using a graphical display.}
118 The real flexibility of this approach is apparent only when you realize
119 that there are many, many different ways to list files. Perhaps you
120 want them sorted by name, sorted by date, in reverse order, or grouped
121 by type. Most graphical browsers have simple ways to express this. But
122 what about showing only a few files, or only files that meet a certain
123 criteria? In very complex and specific situations, the request becomes
124 too difficult to express using a mouse or pointing device. It is just
125 these kinds of requests that are easily solved using a command shell.
127 For example, what if you want to list every Word file on your hard
128 drive, larger than 100 kilobytes in size, and which hasn't been looked
129 at in over six months? That is a good candidate list for deletion, when
130 you go to clean up your hard drive. But have you ever tried asking your
131 computer for such a list? There is no way to do it! At least, not
132 without using a command shell.
134 The role of a command shell is to give you more control over what your
135 computer does for you. Not everyone needs this amount of control, and
136 it does come at a cost: Learning the necessary script commands to
137 express what you want done. A complicated query, such as the example
138 above, takes time to learn. But if you find yourself using your
139 computer frequently enough, it is more than worthwhile in the long run.
140 Any tool you use often deserves the time spent learning to master it.
141 @footnote{For the understandably curious, here is what that command
142 looks like: But don't let it fool you; once you know what's going on,
143 it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.}
145 @section What Eshell is not
146 @cindex Eshell, what it is not
147 @cindex what Eshell is not
148 @cindex what isn't Eshell?
150 Eshell is @emph{not} a replacement for system shells such as
151 @command{bash} or @command{zsh}. Use Eshell when you want to move
152 text between Emacs and external processes; if you only want to pipe
153 output from one external process to another (and then another, and so
154 on), use a system shell, because Emacs's IO system is buffer oriented,
155 not stream oriented, and is very inefficient at such tasks. If you
156 want to write shell scripts in Eshell, don't; either write an elisp
157 library or use a system shell.
159 Some things Eshell just doesn't do well. It fills the niche between
160 IELM and your system shell, where the peculiar use-cases lie, and it
161 is less than ideal outside that niche.
164 * Contributors to Eshell:: People who have helped out!
167 @node Contributors to Eshell
168 @section Contributors to Eshell
172 Contributions to Eshell are welcome. I have limited time to work on
173 this project, but I will gladly add any code you contribute to me to
176 The following persons have made contributions to Eshell.
180 Eli Zaretskii made it possible for Eshell to run without requiring
181 asynchronous subprocess support. This is important for MS-DOS, which
182 does not have such support.
185 Miles Bader contributed many fixes during the port to Emacs 21.
188 Stefan Monnier fixed the things which bothered him, which of course made
189 things better for all.
192 Gerd Moellmann also helped to contribute bug fixes during the initial
193 integration with Emacs 21.
196 Alex Schroeder contributed code for interactively querying the user
197 before overwriting files.
200 Sudish Joseph helped with some XEmacs compatibility issues.
203 Apart from these, a lot of people have sent suggestions, ideas,
204 requests, bug reports and encouragement. Thanks a lot! Without you
205 there would be no new releases of Eshell.
210 In a command shell, everything is done by invoking commands. This
211 chapter covers command invocations in Eshell, including the command
212 history and invoking commands in a script file.
228 Unlike regular system shells, Eshell never invokes kernel functions
229 directly, such as @code{exec(3)}. Instead, it uses the Lisp functions
230 available in the Emacs Lisp library. It does this by transforming the
231 input line into a callable Lisp form.@footnote{To see the Lisp form that will be invoked, type: @samp{eshell-parse-command "echo hello"}}
233 The command can be either an Elisp function or an external command.
234 Eshell looks first for an @ref{Aliases, alias} with the same name as the
235 command, then a @ref{Built-ins, built-in command} or a function with the
236 same name; if there is no match, it then tries to execute it as an
239 The semicolon (@code{;}) can be used to separate multiple command
240 invocations on a single line. A command invocation followed by an
241 ampersand (@code{&}) will be run in the background. Eshell has no job
242 control, so you can not suspend or background the current process, or
243 bring a background process into the foreground. That said, background
244 processes invoked from Eshell can be controlled the same way as any
245 other background process in Emacs.
249 Command arguments are passed to the functions as either strings or
250 numbers, depending on what the parser thinks they look like. If you
251 need to use a function that takes some other data type, you will need to
252 call it in an Elisp expression (which can also be used with
253 @ref{Expansion, expansions}). As with other shells, you can
254 escape special characters and spaces with the backslash (@code{\}) and
255 apostrophes (@code{''}) and double quotes (@code{""}).
259 @section Built-in commands
260 Several commands are built-in in Eshell. In order to call the
261 external variant of a built-in command @code{foo}, you could call
262 @code{*foo}. Usually, this should not be necessary. You can check
263 what will be applied by the @code{which} command:
267 eshell/ls is a compiled Lisp function in `em-ls.el'
272 If you want to discard a given built-in command, you could declare an
273 alias, @ref{Aliases}. Example:
277 eshell/sudo is a compiled Lisp function in `em-unix.el'
278 ~ $ alias sudo '*sudo $*'
280 sudo is an alias, defined as "*sudo $*"
283 @vindex eshell-prefer-lisp-functions
284 If you would prefer to use the built-in commands instead of the external
285 commands, set @code{eshell-prefer-lisp-functions} to @code{t}.
287 Some of the built-in commands have different behavior from their
288 external counterparts, and some have no external counterpart. Most of
289 these will print a usage message when given the @code{--help} option.
295 Adds a given path or set of paths to the PATH environment variable, or,
296 with no arguments, prints the current paths in this variable.
300 Define an alias (@pxref{Aliases}). This does not add it to the aliases
305 Scrolls the contents of the eshell window out of sight, leaving a blank window.
306 If provided with an optional non-nil argument, the scrollback contents are
311 Similar to, but slightly different from, the GNU Coreutils
312 @command{date} command.
317 @xref{Variable Aliases, , , elisp, The Emacs Lisp Reference Manual}.
321 Use Emacs's internal @code{diff} (not to be confused with
322 @code{ediff}). @xref{Comparing Files, , , emacs, The GNU Emacs Manual}.
334 The @command{grep} commands are compatible with GNU @command{grep}, but
335 use Emacs's internal @code{grep} instead.
339 Same as the external @command{info} command, but uses Emacs's internal
344 List subprocesses of the Emacs process, if any, using the function
345 @code{list-processes}.
349 Kill processes. Takes a PID or a process object and an optional
354 Eshell version of @code{list}. Allows you to create a list using Eshell
355 syntax, rather than Elisp syntax. For example, @samp{listify foo bar}
356 and @code{("foo" "bar")} both evaluate to @code{("foo" "bar")}.
360 Alias to Emacs's @code{locate} function, which simply runs the external
361 @command{locate} command and parses the results.
362 @xref{Dired and Find, , , emacs, The GNU Emacs Manual}.
366 Run @command{make} through @code{compile}.
367 @xref{Compilation, , , emacs, The GNU Emacs Manual}.
371 Alias to Emacs's @code{occur}.
372 @xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}.
376 Print the arguments separated by newlines.
380 This command changes the current working directory. Usually, it is
381 invoked as @samp{cd foo} where @file{foo} is the new working directory.
382 But @command{cd} knows about a few special arguments:
384 When it receives no argument at all, it changes to the home directory.
386 Giving the command @samp{cd -} changes back to the previous working
387 directory (this is the same as @samp{cd $-}).
389 The command @samp{cd =} shows the directory stack. Each line is
392 With @samp{cd =foo}, Eshell searches the directory stack for a directory
393 matching the regular expression @samp{foo} and changes to that
396 With @samp{cd -42}, you can access the directory stack by number.
402 Uses TRAMP's @command{su} or @command{sudo} method @pxref{Inline methods, , , tramp}
403 to run a command via @command{su} or @command{sudo}. These commands
404 are in the eshell-tramp module, which is disabled by default.
408 @subsection Built-in variables
409 Eshell knows a few built-in variables:
415 This variable always contains the current working directory.
419 This variable always contains the previous working directory (the
420 current working directory from before the last @code{cd} command).
424 It refers to the last argument of the last command.
428 This is the result of the last command. In case of an external
429 command, it is @code{t} or @code{nil}.
433 This variable contains the exit code of the last command (0 or 1 for
434 Lisp functions, based on successful completion).
440 Since Eshell is just an Emacs REPL@footnote{Read-Eval-Print Loop}, it
441 does not have its own scope, and simply stores variables the same you
442 would in an Elisp program. Eshell provides a command version of
443 @code{setq} for convenience.
448 Aliases are commands that expand to a longer input line. For example,
449 @command{ll} is a common alias for @code{ls -l}, and would be defined
450 with the command invocation @samp{alias ll ls -l}; with this defined,
451 running @samp{ll foo} in Eshell will actually run @samp{ls -l foo}.
452 Aliases defined (or deleted) by the @command{alias} command are
453 automatically written to the file named by @code{eshell-aliases-file},
454 which you can also edit directly (although you will have to manually
460 The @samp{history} command shows all commands kept in the history ring
461 as numbered list. If the history ring contains
462 @code{eshell-history-size} commands, those numbers change after every
463 command invocation, therefore the @samp{history} command shall be
464 applied before using the expansion mechanism with history numbers.
466 The n-th entry of the history ring can be applied with the @samp{!n}
467 command. If @code{n} is negative, the entry is counted from the end
470 @samp{!foo} expands to the last command beginning with @code{foo}, and
471 @samp{!?foo} to the last command containing @code{foo}. The n-th
472 argument of the last command beginning with @code{foo} is accessible
475 The history ring is loaded from a file at the start of every session,
476 and written back to the file at the end of every session. The file path
477 is specified in @code{eshell-history-file-name}. Unlike other shells,
478 such as Bash, Eshell can not be configured to keep a history ring of a
479 different size than that of the history file.
481 Since the default buffer navigation and searching key-bindings are
482 still present in the Eshell buffer, the commands for history
483 navigation and searching are bound to different keys:
492 Previous and next history line. If there is anything on the input
493 line when you run these commands, they will instead jump to the
494 precious or next line that begins with that string.
499 Eshell uses the pcomplete package for programmable completion, similar
500 to that of other command shells. Argument completion differs depending
501 on the preceding command: for example, possible completions for
502 @command{rmdir} are only directories, while @command{rm} completions can
503 be directories @emph{and} files. Eshell provides predefined completions
504 for the built-in functions and some common external commands, and you
505 can define your own for any command.
507 Eshell completion also works for lisp forms and glob patterns. If the
508 point is on a lisp form, then @key{TAB} will behave similarly to completion
509 in @code{elisp-mode} and @code{lisp-interaction-mode}. For glob
510 patterns, If there are few enough possible completions of the patterns,
511 they will be cycled when @key{TAB} is pressed, otherwise it will be removed
512 from the input line and the possible completions will be listed.
514 If you want to see the entire list of possible completions when it's
515 below the cycling threshold, press @kbd{M-?}.
517 @subsection pcomplete
518 Pcomplete, short for programmable completion, is the completion
519 library originally written for Eshell, but usable for command
520 completion@footnote{Command completion as opposed to code completion,
521 which is a beyond the scope of pcomplete.} in other modes.
523 Completions are defined as functions (with @code{defun}) named
524 @code{pcomplete/COMMAND}, where @code{COMMAND} is the name of the
525 command for which this function provides completions; you can also name
526 the function @code{pcomplete/MAJOR-MODE/COMMAND} to define completions
527 for a specific major mode.
530 @section @code{for} loop
531 Because Eshell commands can not (easily) be combined with lisp forms,
532 Eshell provides a command-oriented @command{for}-loop for convenience.
533 The syntax is as follows:
536 @code{for VAR in TOKENS @{ command invocation(s) @}}
539 where @samp{TOKENS} is a space-separated sequence of values of
540 @var{VAR} for each iteration. This can even be the output of a
541 command if @samp{TOKENS} is replaced with @samp{@{ command invocation @}}.
546 @fnindex eshell-source-file
547 You can run Eshell scripts much like scripts for other shells; the main
548 difference is that since Eshell is not a system command, you have to run
549 it from within Emacs. An Eshell script is simply a file containing a
550 sequence of commands, as with almost any other shell script. Scripts
551 are invoked from Eshell with @command{source}, or from anywhere in Emacs
552 with @code{eshell-source-file}.
555 If you wish to load a script into your @emph{current} environment,
556 rather than in a subshell, use the @code{.} command.
560 Expansion in a command shell is somewhat like macro expansion in macro
561 parsers (such as @command{cpp} and @command{m4}), but in a command
562 shell, they are less often used for constants, and usually for using
563 variables and string manipulation.@footnote{Eshell has no
564 string-manipulation expansions because the Elisp library already
565 provides many functions for this.} For example, @code{$var} on a line
566 expands to the value of the variable @code{var} when the line is
567 executed. Expansions are usually passed as arguments, but may also be
568 used as commands.@footnote{E.g., entering just @samp{$var} at the prompt
569 is equivalent to entering the value of @code{var} at the prompt.}
572 * Dollars Expansion::
576 @node Dollars Expansion
577 @section Dollars Expansion
578 Eshell has different @code{$} expansion syntax from other shells. There
579 are some similarities, but don't let these lull you into a false sense
585 Expands to the value bound to @code{var}. This is the main way to use
586 variables in command invocations.
589 Expands to the length of the value bound to @code{var}. Raises an error
590 if the value is not a sequence
591 (@pxref{Sequences Arrays Vectors, Sequences, , elisp, The Emacs Lisp Reference Manual}).
594 Expands to the result of evaluating the S-expression @code{(lisp)}. On
595 its own, this is identical to just @code{(lisp)}, but with the @code{$},
596 it can be used in a string, such as @samp{/some/path/$(lisp).txt}.
599 Returns the output of @command{command}, which can be any valid Eshell
600 command invocation, and may even contain expansions.
603 Expands to the @code{i}th element of the value bound to @code{var}. If
604 the value is a string, it will be split at whitespace to make it a list.
605 Again, raises an error if the value is not a sequence.
608 As above, but now splitting occurs at the colon character.
611 As above, but instead of returning just a string, it now returns a list
612 of two strings. If the result is being interpolated into a larger
613 string, this list will be flattened into one big string, with each
614 element separated by a space.
617 Separate on backslash characters. Actually, the first argument -- if it
618 doesn't have the form of a number, or a plain variable name -- can be
619 any regular expression. So to split on numbers, use @samp{$var["[0-9]+" 10 20]}.
622 Calls @code{assoc} on @code{var} with @code{"hello"}, expecting it to be
623 an alist (@pxref{Association List Type, Association Lists, , elisp,
624 The Emacs Lisp Reference Manual}).
627 Returns the length of the cdr of the element of @code{var} who car is equal
634 Eshell's globbing syntax is very similar to that of Zsh. Users coming
635 from Bash can still use Bash-style globbing, as there are no
636 incompatibilities. Most globbing is pattern-based expansion, but there
637 is also predicate-based expansion. See
638 @ref{Filename Generation, , , zsh, The Z Shell Manual}
639 for full syntax. To customize the syntax and behavior of globbing in
640 Eshell see the Customize@footnote{@xref{Easy Customization, , , emacs,
641 The GNU Emacs Manual}.}
642 groups ``eshell-glob'' and ``eshell-pred''.
645 @chapter Input/Output
646 Since Eshell does not communicate with a terminal like most command
647 shells, IO is a little different.
649 @section Visual Commands
650 If you try to run programs from within Eshell that are not
651 line-oriented, such as programs that use ncurses, you will just get
652 garbage output, since the Eshell buffer is not a terminal emulator.
653 Eshell solves this problem by running such programs in Emacs's
656 Programs that need a terminal to display output properly are referred
657 to in this manual as ``visual commands,'' because they are not simply
658 line-oriented. You must tell Eshell which commands are visual, by
659 adding them to @code{eshell-visual-commands}; for commands that are
660 visual for only certain @emph{sub}-commands -- e.g., @samp{git log} but
661 not @samp{git status} -- use @code{eshell-visual-subcommands}; and for
662 commands that are visual only when passed certain options, use
663 @code{eshell-visual-options}.
665 Caution: Some tools such as Git use the pager @samp{less} by default
666 to paginate their output but call it with its @samp{-F} option. This
667 option causes @samp{less} to echo the output instead of paginating it
668 if the output is less than one page long. This causes undesirable
669 behavior if, e.g., @samp{git diff}, is defined as a visual subcommand.
670 It'll work if the output is big enough and fail if it is less than one
671 page long. If that occurs to you, search for configuration options
672 for calling @samp{less} without the @samp{-F} option. For Git, you
673 can do that using @samp{git config --global core.pager 'less -+F'}.
675 @vindex eshell-destroy-buffer-when-process-dies
676 If you want the buffers created by visual programs killed when the
677 program exits, customize the variable
678 @code{eshell-destroy-buffer-when-process-dies} to a non-@code{nil}
679 value; the default is @code{nil}.
682 Redirection is mostly the same in Eshell as it is in other command
683 shells. The output redirection operators @code{>} and @code{>>} as
684 well as pipes are supported, but there is not yet any support for
685 input redirection. Output can also be redirected to buffers, using
686 the @code{>>>} redirection operator, and Elisp functions, using
689 The buffer redirection operator, @code{>>>}, expects a buffer object
690 on the right-hand side, into which it inserts the output of the
691 left-hand side. e.g., @samp{echo hello >>> #<buffer *scratch*>}
692 inserts the string @code{"hello"} into the @file{*scratch*} buffer.
693 The convenience shorthand variant @samp{#<@var{buffer-name}>}, as in
694 @samp{#<*scratch*>}, is also accepted.
696 @code{eshell-virtual-targets} is a list of mappings of virtual device
697 names to functions. Eshell comes with two virtual devices:
698 @file{/dev/kill}, which sends the text to the kill ring, and
699 @file{/dev/clip}, which sends text to the clipboard.
701 You can, of course, define your own virtual targets. They are defined
702 by adding a list of the form @samp{("/dev/name" @var{function} @var{mode})} to
703 @code{eshell-virtual-targets}. The first element is the device name;
704 @var{function} may be either a lambda or a function name. If
705 @var{mode} is @code{nil}, then the function is the output function; if it is
706 non-@code{nil}, then the function is passed the redirection mode as a
707 symbol--@code{overwrite} for @code{>}, @code{append} for @code{>>}, or
708 @code{insert} for @code{>>>}--and the function is expected to return
711 The output function is called once on each line of output until
712 @code{nil} is passed, indicating end of output.
714 @node Extension modules
715 @chapter Extension modules
716 Eshell provides a facility for defining extension modules so that they
717 can be disabled and enabled without having to unload and reload them,
718 and to provide a common parent Customize group for the
719 modules.@footnote{ERC provides a similar module facility.} An Eshell
720 module is defined the same as any other library but one requirement: the
721 module must define a Customize@footnote{@xref{Customization, , ,
722 elisp, The Emacs Lisp Reference Manual}.}
723 group using @code{eshell-defgroup} (in place of @code{defgroup}) with
724 @code{eshell-module} as the parent group.@footnote{If the module has
725 no user-customizable options, then there is no need to define it as an
726 Eshell module.} You also need to load the following as shown:
740 * Directory handling::
743 * Terminal emulation::
746 @node Writing a module
747 @section Writing a module
750 @section Module testing
752 @node Directory handling
753 @section Directory handling
756 @section Key rebinding
758 @node Smart scrolling
759 @section Smart scrolling
761 @node Terminal emulation
762 @section Terminal emulation
765 @chapter Bugs and ideas
766 @cindex reporting bugs and ideas
767 @cindex bugs, how to report them
768 @cindex author, how to reach
769 @cindex email to the author
771 @cindex problems, list of common
775 If you find a bug or misfeature, don't hesitate to report it, by
776 using @kbd{M-x report-emacs-bug}. The same applies to feature requests.
777 It is best to discuss one thing at a time. If you find several
778 unrelated bugs, please report them separately.
781 If you have ideas for improvements, or if you have written some
782 extensions to this package, I would like to hear from you. I hope you
783 find this package useful!
786 Below is a list of some known problems with Eshell version 2.4.2,
787 which is the version included with Emacs 22.
790 @item Documentation incomplete
792 @item Differentiate between aliases and functions
794 Allow for a Bash-compatible syntax, such as:
798 function arg () @{ blah $* @}
801 @item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt
803 In fact, piping to a process from a looping construct doesn't work in
804 general. If I change the call to @code{eshell-copy-handles} in
805 @code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems
806 to work, but the output occurs after the prompt is displayed. The whole
807 structured command thing is too complicated at present.
809 @item Error with @command{bc} in @code{eshell-test}
811 On some XEmacs system, the subprocess interaction test fails
812 inexplicably, although @command{bc} works fine at the command prompt.
814 @item Eshell does not delete @file{*Help*} buffers in XEmacs 21.1.8+
816 In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that
817 multiple instances of the @file{*Help*} buffer can exist.
819 @item Pcomplete sometimes gets stuck
821 You press @key{TAB}, but no completions appear, even though the
822 directory has matching files. This behavior is rare.
824 @item @samp{grep python $<rpm -qa>} doesn't work, but using @samp{*grep} does
826 This happens because the @code{grep} Lisp function returns immediately,
827 and then the asynchronous @command{grep} process expects to examine the
828 temporary file, which has since been deleted.
830 @item Problem with C-r repeating text
832 If the text @emph{before point} reads "./run", and you type @kbd{C-r r u
833 n}, it will repeat the line for every character typed.
835 @item Backspace doesn't scroll back after continuing (in smart mode)
837 Hitting space during a process invocation, such as @command{make}, will
838 cause it to track the bottom of the output; but backspace no longer
841 @item It's not possible to fully @code{unload-feature} Eshell
843 @item Menu support was removed, but never put back
845 @item Using C-p and C-n with rebind gets into a locked state
847 This happened a few times in Emacs 21, but has been irreproducible
850 @item If an interactive process is currently running, @kbd{M-!} doesn't work
852 @item Use a timer instead of @code{sleep-for} when killing child processes
854 @item Piping to a Lisp function is not supported
856 Make it so that the Lisp command on the right of the pipe is repeatedly
857 called with the input strings as arguments. This will require changing
858 @code{eshell-do-pipeline} to handle non-process targets.
860 @item Input redirection is not supported
864 @item Problem running @command{less} without arguments on Windows
866 The result in the Eshell buffer is:
869 Spawning child process: invalid argument
872 Also a new @command{less} buffer was created with nothing in it@dots{}
873 (presumably this holds the output of @command{less}).
875 If @command{less.exe} is invoked from the Eshell command line, the
876 expected output is written to the buffer.
878 Note that this happens on NT-Emacs 20.6.1 on Windows 2000. The term.el
879 package and the supplied shell both use the @command{cmdproxy} program
882 @item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp}
884 @item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be
886 @item @samp{mv @var{dir} @var{file}.tar} does not remove directories
888 This is because the tar option --remove-files doesn't do so. Should it
891 @item Bind @code{standard-output} and @code{standard-error}
893 This would be so that if a Lisp function calls @code{print}, everything
894 will happen as it should (albeit slowly).
896 @item When an extension module fails to load, @samp{cd /} gives a Lisp error
898 @item If a globbing pattern returns one match, should it be a list?
900 @item Make sure syntax table is correct in Eshell mode
902 So that @kbd{M-DEL} acts in a predictable manner, etc.
904 @item Allow all Eshell buffers to share the same history and list-dir
906 @item There is a problem with script commands that output to @file{/dev/null}
908 If a script file, somewhere in the middle, uses @samp{> /dev/null},
909 output from all subsequent commands is swallowed.
911 @item Split up parsing of text after @samp{$} in @file{esh-var.el}
913 Make it similar to the way that @file{esh-arg.el} is structured.
914 Then add parsing of @samp{$[?\n]}.
916 @item After pressing @kbd{M-RET}, redisplay before running the next command
918 @item Argument predicates and modifiers should work anywhere in a path
921 /usr/local/src/editors/vim $ vi **/CVS(/)/Root(.)
922 Invalid regexp: "Unmatched ( or \\("
925 With @command{zsh}, the glob above expands to all files named
926 @file{Root} in directories named @file{CVS}.
928 @item Typing @samp{echo $@{locate locate@}/bin<TAB>} results in a Lisp error
930 Perhaps it should interpolate all permutations, and make that the
931 globbing result, since otherwise hitting return here will result in
932 ``(list of filenames)/bin'', which is never valuable. Thus, one could
933 @command{cat} only C backup files by using @samp{ls $@{identity *.c@}~}.
934 In that case, having an alias command name @command{glob} for
935 @command{identity} would be useful.
937 @item Once symbolic mode is supported for @command{umask}, implement @command{chmod} in Lisp
939 @item Create @code{eshell-expand-file-name}
941 This would use a data table to transform things such as @samp{~+},
944 @item Abstract @file{em-smart.el} into @file{smart-scroll.el}
946 It only really needs: to be hooked onto the output filter and the
947 pre-command hook, and to have the input-end and input-start markers.
948 And to know whether the last output group was ``successful.''
950 @item Allow for fully persisting the state of Eshell
952 This would include: variables, history, buffer, input, dir stack, etc.
954 @item Implement D as an argument predicate
956 It means that files beginning with a dot should be included in the
959 @item A comma in a predicate list should mean OR
961 At the moment, this is not supported.
963 @item Error if a glob doesn't expand due to a predicate
965 An error should be generated only if @code{eshell-error-if-no-glob} is
968 @item @samp{(+ RET SPC TAB} does not cause @code{indent-according-to-mode} to occur
970 @item Create @code{eshell-auto-accumulate-list}
972 This is a list of commands for which, if the user presses @kbd{RET}, the
973 text is staged as the next Eshell command, rather than being sent to the
974 current interactive process.
976 @item Display file and line number if an error occurs in a script
978 @item @command{wait} doesn't work with process ids at the moment
980 @item Enable the direct-to-process input code in @file{em-term.el}
982 @item Problem with repeating @samp{echo $@{find /tmp@}}
984 With smart display active, if @kbd{RET} is held down, after a while it
985 can't keep up anymore and starts outputting blank lines. It only
986 happens if an asynchronous process is involved@dots{}
988 I think the problem is that @code{eshell-send-input} is resetting the
989 input target location, so that if the asynchronous process is not done
990 by the time the next @kbd{RET} is received, the input processor thinks
991 that the input is meant for the process; which, when smart display is
992 enabled, will be the text of the last command line! That is a bug in
995 In holding down @kbd{RET} while an asynchronous process is running,
996 there will be a point in between termination of the process, and the
997 running of @code{eshell-post-command-hook}, which would cause
998 @code{eshell-send-input} to call @code{eshell-copy-old-input}, and then
999 process that text as a command to be run after the process. Perhaps
1000 there should be a way of killing pending input between the death of the
1001 process, and the @code{post-command-hook}.
1003 @item Allow for a more aggressive smart display mode
1005 Perhaps toggled by a command, that makes each output block a smart
1008 @item Create more meta variables
1012 The reason for the failure of the last disk command, or the text of the
1016 A special associate array, which can take references of the form
1017 @samp{$=[REGEXP]}. It indexes into the directory ring.
1020 @item Eshell scripts can't execute in the background
1022 @item Support zsh's ``Parameter Expansion'' syntax, i.e., @samp{$@{@var{name}:-@var{val}@}}
1024 @item Write an @command{info} alias that can take arguments
1026 So that the user can enter @samp{info chmod}, for example.
1028 @item Create a mode @code{eshell-browse}
1030 It would treat the Eshell buffer as a outline. Collapsing the outline
1031 hides all of the output text. Collapsing again would show only the
1032 first command run in each directory
1034 @item Allow other revisions of a file to be referenced using @samp{file@{rev@}}
1036 This would be expanded by @code{eshell-expand-file-name} (see above).
1038 @item Print ``You have new mail'' when the ``Mail'' icon is turned on
1040 @item Implement @kbd{M-|} for Eshell
1042 @item Implement input redirection
1044 If it's a Lisp function, input redirection implies @command{xargs} (in a
1045 way@dots{}). If input redirection is added, also update the
1046 @code{file-name-quote-list}, and the delimiter list.
1048 @item Allow @samp{#<@var{word} @var{arg}>} as a generic syntax
1050 With the handling of @emph{word} specified by an
1051 @code{eshell-special-alist}.
1053 @item In @code{eshell-eval-using-options}, allow a @code{:complete} tag
1055 It would be used to provide completion rules for that command. Then the
1056 macro will automagically define the completion function.
1058 @item For @code{eshell-command-on-region}, apply redirections to the result
1060 So that @samp{+ > 'blah} would cause the result of the @code{+} (using
1061 input from the current region) to be inserting into the symbol
1064 If an external command is being invoked, the input is sent as standard
1065 input, as if a @samp{cat <region> |} had been invoked.
1067 If a Lisp command, or an alias, is invoked, then if the line has no
1068 newline characters, it is divided by whitespace and passed as arguments
1069 to the Lisp function. Otherwise, it is divided at the newline
1070 characters. Thus, invoking @code{+} on a series of numbers will add
1071 them; @code{min} would display the smallest figure, etc.
1073 @item Write @code{eshell-script-mode} as a minor mode
1075 It would provide syntax, abbrev, highlighting and indenting support like
1076 @code{emacs-lisp-mode} and @code{shell-mode}.
1078 @item In the history mechanism, finish the Bash-style support
1080 This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate
1083 @item Support the -n command line option for @command{history}
1085 @item Implement @command{fc} in Lisp
1087 @item Specifying a frame as a redirection target should imply the currently active window's buffer
1089 @item Implement @samp{>@var{func-or-func-list}}
1091 This would allow for an ``output translators'', that take a function to
1092 modify output with, and a target. Devise a syntax that works well with
1093 pipes, and can accommodate multiple functions (i.e., @samp{>'(upcase
1094 regexp-quote)} or @samp{>'upcase}).
1096 @item Allow Eshell to read/write to/from standard input and output
1098 This would be optional, rather than always using the Eshell buffer.
1099 This would allow it to be run from the command line (perhaps).
1101 @item Write a @command{help} command
1103 It would call subcommands with @option{--help}, or @option{-h} or
1104 @option{/?}, as appropriate.
1106 @item Implement @command{stty} in Lisp
1108 @item Support @command{rc}'s matching operator, e.g., @samp{~ (@var{list}) @var{regexp}}
1110 @item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list}
1112 Using @command{bg} on a process that is already in the background does
1113 nothing. Specifying redirection targets replaces (or adds) to the list
1116 @item Have @command{jobs} print only the processes for the current shell
1118 @item How can Eshell learn if a background process has requested input?
1120 @item Support @samp{2>&1} and @samp{>&} and @samp{2>} and @samp{|&}
1122 The syntax table for parsing these should be customizable, such that the
1123 user could change it to use rc syntax: @samp{>[2=1]}.
1125 @item Allow @samp{$_[-1]}, which would indicate the last element of the array
1127 @item Make @samp{$x[*]} equal to listing out the full contents of @samp{x}
1129 Return them as a list, so that @samp{$_[*]} is all the arguments of the
1132 @item Copy ANSI code handling from @file{term.el} into @file{em-term.el}
1134 Make it possible for the user to send char-by-char to the underlying
1135 process. Ultimately, I should be able to move away from using term.el
1136 altogether, since everything but the ANSI code handling is already part
1137 of Eshell. Then, things would work correctly on MS-Windows as well
1138 (which doesn't have @file{/bin/sh}, although @file{term.el} tries to use
1141 @item Make the shell spawning commands be visual
1143 That is, make (@command{su}, @command{bash}, @command{telnet},
1144 @command{rlogin}, @command{rsh}, etc.)@: be part of
1145 @code{eshell-visual-commands}. The only exception is if the shell is
1146 being used to invoke a single command. Then, the behavior should be
1147 based on what that command is.
1149 @item Create a smart viewing command named @command{open}
1151 This would search for some way to open its argument (similar to opening
1152 a file in the Windows Explorer).
1154 @item Alias @command{read} to be the same as @command{open}, only read-only
1156 @item Write a @command{tail} command which uses @code{view-file}
1158 It would move point to the end of the buffer, and then turns on
1159 auto-revert mode in that buffer at frequent intervals---and a
1160 @command{head} alias which assumes an upper limit of
1161 @code{eshell-maximum-line-length} characters per line.
1163 @item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search}
1165 @item Write @file{mesh.c}
1167 This would run Emacs with the appropriate arguments to invoke Eshell
1168 only. That way, it could be listed as a login shell.
1170 @item Use an intangible @code{PS2} string for multi-line input prompts
1172 @item Auto-detect when a command is visual, by checking @code{TERMCAP} usage
1174 @item The first keypress after @kbd{M-x watson} triggers
1175 @code{eshell-send-input}
1177 @item Make @kbd{/} electric
1179 So that it automatically expands and corrects pathnames. Or make
1180 pathname completion for Pcomplete auto-expand @samp{/u/i/std<TAB>} to
1181 @samp{/usr/include/std<TAB>}.
1183 @item Write the @command{pushd} stack to disk along with @code{last-dir-ring}
1185 @item Add options to @code{eshell/cat} which would allow it to sort and uniq
1187 @item Implement @command{wc} in Lisp
1189 Add support for counting sentences, paragraphs, pages, etc.
1191 @item Once piping is added, implement @command{sort} and @command{uniq} in Lisp
1193 @item Implement @command{touch} in Lisp
1195 @item Implement @command{comm} in Lisp
1197 @item Implement an @command{epatch} command in Lisp
1199 This would call @code{ediff-patch-file}, or @code{ediff-patch-buffer},
1200 depending on its argument.
1202 @item Have an option such that @samp{ls -l} generates a dired buffer
1204 @item Write a version of @command{xargs} based on command rewriting
1206 That is, @samp{find X | xargs Y} would be indicated using @samp{Y
1207 $@{find X@}}. Maybe @code{eshell-do-pipelines} could be changed to
1208 perform this on-thy-fly rewriting.
1210 @item Write an alias for @command{less} that brings up a @code{view-mode} buffer
1212 Such that the user can press @key{SPC} and @key{DEL}, and then @key{q}
1213 to return to Eshell. It would be equivalent to:
1214 @samp{X > #<buffer Y>; view-buffer #<buffer Y>}.
1216 @item Make @code{eshell-mode} as much a full citizen as @code{shell-mode}
1218 Everywhere in Emacs where @code{shell-mode} is specially noticed, add
1219 @code{eshell-mode} there.
1221 @item Permit the umask to be selectively set on a @command{cp} target
1223 @item Problem using @kbd{M-x eshell} after using @code{eshell-command}
1225 If the first thing that I do after entering Emacs is to run
1226 @code{eshell-command} and invoke @command{ls}, and then use @kbd{M-x
1227 eshell}, it doesn't display anything.
1229 @item @kbd{M-RET} during a long command (using smart display) doesn't work
1231 Since it keeps the cursor up where the command was invoked.
1235 @node GNU Free Documentation License
1236 @appendix GNU Free Documentation License
1237 @include doclicense.texi
1240 @unnumbered Concept Index
1244 @node Function and Variable Index
1245 @unnumbered Function and Variable Index
1250 @unnumbered Command Index
1254 @c There are no @kindex entries in this manual; avoid generating an
1258 @unnumbered Key Index