1 \input texinfo @c -*-texinfo-*-
3 @setfilename ../../info/eshell
4 @settitle Eshell: The Emacs Shell
10 This manual is for Eshell, the Emacs shell.
12 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
13 2007, 2008, 2009, 2010, 2011, 2012 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. Buying copies from the FSF supports it in
25 developing GNU and promoting software freedom.''
29 @dircategory Emacs misc features
31 * Eshell: (eshell). A command shell implemented in Emacs Lisp.
36 @c The title is printed in a large font.
37 @center @titlefont{User's Guide}
39 @center @titlefont{to}
41 @center @titlefont{Eshell: The Emacs Shell}
48 @center John Wiegley & Aidan Gauland
52 @vskip 0pt plus 1filll
58 @c ================================================================
59 @c The real text starts here
60 @c ================================================================
63 @node Top, What is Eshell?, (dir), (dir)
66 Eshell is a shell-like command interpretor
67 implemented in Emacs Lisp. It invokes no external processes except for
68 those requested by the user. It is intended to be a functional
69 replacement for command shells such as @command{bash}, @command{zsh},
70 @command{rc}, or @command{4dos}; since Emacs itself is capable of
71 handling the sort of tasks accomplished by those tools.
72 @c This manual is updated to release 2.4 of Eshell.
78 * What is Eshell?:: A brief introduction to the Emacs Shell.
79 * Command basics:: The basics of command usage.
84 * Bugs and ideas:: Known problems, and future ideas.
85 * GNU Free Documentation License:: The license for this documentation.
87 * Function and Variable Index::
93 @chapter What is Eshell?
94 @cindex what is Eshell?
95 @cindex Eshell, what it is
97 Eshell is a @dfn{command shell} written in Emacs Lisp. Everything it
98 does, it uses Emacs' facilities to do. This means that Eshell is as
99 portable as Emacs itself. It also means that cooperation with Lisp code
100 is natural and seamless.
102 What is a command shell? To properly understand the role of a shell,
103 it's necessary to visualize what a computer does for you. Basically, a
104 computer is a tool; in order to use that tool, you must tell it what to
105 do---or give it ``commands.'' These commands take many forms, such as
106 clicking with a mouse on certain parts of the screen. But that is only
107 one form of command input.
109 By far the most versatile way to express what you want the computer to
110 do is by using an abbreviated language called @dfn{script}. In
111 script, instead of telling the computer, ``list my files, please'',
112 one writes a standard abbreviated command word---@samp{ls}. Typing
113 @samp{ls} in a command shell is a script way of telling the computer
114 to list your files.@footnote{This is comparable to viewing the
115 contents of a folder using a graphical display.}
117 The real flexibility of this approach is apparent only when you realize
118 that there are many, many different ways to list files. Perhaps you
119 want them sorted by name, sorted by date, in reverse order, or grouped
120 by type. Most graphical browsers have simple ways to express this. But
121 what about showing only a few files, or only files that meet a certain
122 criteria? In very complex and specific situations, the request becomes
123 too difficult to express using a mouse or pointing device. It is just
124 these kinds of requests that are easily solved using a command shell.
126 For example, what if you want to list every Word file on your hard
127 drive, larger than 100 kilobytes in size, and which hasn't been looked
128 at in over six months? That is a good candidate list for deletion, when
129 you go to clean up your hard drive. But have you ever tried asking your
130 computer for such a list? There is no way to do it! At least, not
131 without using a command shell.
133 The role of a command shell is to give you more control over what your
134 computer does for you. Not everyone needs this amount of control, and
135 it does come at a cost: Learning the necessary script commands to
136 express what you want done. A complicated query, such as the example
137 above, takes time to learn. But if you find yourself using your
138 computer frequently enough, it is more than worthwhile in the long run.
139 Any tool you use often deserves the time spent learning to master it.
140 @footnote{For the understandably curious, here is what that command
141 looks like: But don't let it fool you; once you know what's going on,
142 it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.}
145 * Contributors to Eshell:: People who have helped out!
148 @node Contributors to Eshell
149 @section Contributors to Eshell
153 Contributions to Eshell are welcome. I have limited time to work on
154 this project, but I will gladly add any code you contribute to me to
157 The following persons have made contributions to Eshell.
161 Eli Zaretskii made it possible for Eshell to run without requiring
162 asynchronous subprocess support. This is important for MS-DOS, which
163 does not have such support.@refill
166 Miles Bader contributed many fixes during the port to Emacs 21.@refill
169 Stefan Monnier fixed the things which bothered him, which of course made
170 things better for all.@refill
173 Gerd Moellmann also helped to contribute bug fixes during the initial
174 integration with Emacs 21.@refill
177 Alex Schroeder contributed code for interactively querying the user
178 before overwriting files.@refill
181 Sudish Joseph helped with some XEmacs compatibility issues.@refill
184 Apart from these, a lot of people have sent suggestions, ideas,
185 requests, bug reports and encouragement. Thanks a lot! Without you
186 there would be no new releases of Eshell.
189 @chapter Basic overview
191 A command shell is a means of entering verbally-formed commands. This
192 is really all that it does, and every feature described in this manual
193 is a means to that end. Therefore, it's important to take firm hold on
194 exactly what a command is, and how it fits in the overall picture of
198 * Commands verbs:: Commands always begin with a verb.
199 * Command arguments:: Some verbs require arguments.
203 @section Commands verbs
205 Commands are expressed using @dfn{script}, a special shorthand language
206 computers can understand with no trouble. Script is an extremely simple
207 language; oddly enough, this is what makes it look so complicated!
208 Whereas normal languages use a variety of embellishments, the form of a
209 script command is always:
212 @var{verb} [@var{arguments}]
215 The verb expresses what you want your computer to do. There are a fixed
216 number of verbs, although this number is usually quite large. On the
217 author's computer, it reaches almost 1400 in number. But of course,
218 only a handful of these are really necessary.
220 Sometimes, the verb is all that's written. A verb is always a single
221 word, usually related to the task it performs. @command{reboot} is a
222 good example. Entering that on GNU/Linux will reboot the
223 computer---assuming you have sufficient privileges.
225 Other verbs require more information. These are usually very capable
226 verbs, and must be told specifically what to do. The extra information
227 is given in the form of @dfn{arguments}. For example, the
228 @command{echo} verb prints back whatever arguments you type. It
229 requires these arguments to know what to echo. A proper use of
230 @command{echo} looks like this:
233 echo This is an example of using echo!
236 This script command causes the computer to echo back: ``This is an
237 example of using echo!''
239 Although command verbs are always simple words, like @command{reboot} or
240 @command{echo}, arguments may have a wide variety of forms. There are
241 textual arguments, numerical arguments---even Lisp arguments.
242 Distinguishing these different types of arguments requires special
243 typing, for the computer to know exactly what you mean.
245 @node Command arguments
246 @section Command arguments
248 Eshell recognizes several different kinds of command arguments:
251 @item Strings (also called textual arguments)
252 @item Numbers (floating point or integer)
256 @item Emacs process handles
259 Most users need to worry only about the first two. The third, Lisp lists,
260 occur very frequently, but almost always behind the scenes.
262 Strings are the most common type of argument, and consist of nearly any
263 character. Special characters---those used by Eshell
264 specifically---must be preceded by a backslash (@samp{\}). When in doubt, it
265 is safe to add backslashes anywhere and everywhere.
267 Here is a more complicated @command{echo} example:
270 echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar
273 Beyond this, things get a bit more complicated. While not beyond the
274 reach of someone wishing to learn, it is definitely beyond the scope of
275 this manual to present it all in a simplistic manner. Get comfortable
276 with Eshell as a basic command invocation tool, and learn more about the
277 commands on your system; then come back when it all sits more familiarly
278 on your mind. Have fun!
283 In a command shell, everything is done by invoking commands. This
284 chapter covers command invocations in Eshell, including the command
285 history and invoking commands in a script file.
301 Unlike regular system shells, Eshell never invokes kernel functions
302 directly, such as @code{exec(3)}. Instead, it uses the Lisp functions
303 available in the Emacs Lisp library. It does this by transforming the
304 input line into a callable Lisp form.@footnote{To see the Lisp form that will be invoked, type: @samp{eshell-parse-command "echo hello"}}
306 The command can be either an Elisp function or an external command.
307 Eshell looks first for an @ref{Aliases, alias} with the same name as the
308 command, then a @ref{Built-ins, built-in command} or a function with the
309 same name; if there is no match, it then tries to execute it as an
312 The semicolon (@code{;}) can be used to separate multiple command
313 invocations on a single line. A command invocation followed by an
314 ampersand (@code{&}) will be run in the background. Eshell has no job
315 control, so you can not suspend or background the current process, or
316 bring a background process into the foreground. That said, background
317 processes invoked from Eshell can be controlled the same way as any
318 other background process in Emacs.
322 Command arguments are passed to the functions as either strings or
323 numbers, depending on what the parser thinks they look like. If you
324 need to use a function that takes some other data type, you will need to
325 call it in an Elisp expression (which can also be used with
326 @ref{Expansion, expansions}). As with other shells, you can
327 escape special characters and spaces with the backslash (@code{\}) and
328 the single (@code{''}) and double (@code{""}) quotes.
332 @section Built-in commands
333 Several commands are built-in in Eshell. In order to call the
334 external variant of a built-in command @code{foo}, you could call
335 @code{*foo}. Usually, this should not be necessary. You can check
336 what will be applied by the @code{which} command:
340 eshell/ls is a compiled Lisp function in `em-ls.el'
345 @vindex eshell-prefer-lisp-functions
346 If you would prefer to use the built-in commands instead of the external
347 commands, set @var{eshell-prefer-lisp-functions} to @code{t}.
349 Some of the built-in commands have different behaviour from their
350 external counterparts, and some have no external counterpart. Most of
351 these will print a useage message when given the @code{--help} option.
357 Adds a given path or set of paths to the PATH environment variable, or,
358 with no arguments, prints the current paths in this variable.
362 Define an alias (@pxref{Aliases}). This does not add it to the aliases
367 Similar to, but slightly different from, the GNU Coreutils
368 @command{date} command.
372 Define a varalias. @xref{Variable Aliases, , , elisp}.
376 Use Emacs's internal @code{diff} (not to be confused with
377 @code{ediff}). @xref{Comparing Files, , , elisp}.
389 The @command{grep} commands are compatible with GNU @command{grep}, but
390 use Emacs's internal @code{grep} instead.
394 Same as the external @command{info} command, but uses Emacs's internal
399 List subprocesses of the Emacs process, if any, using the function
400 @code{list-processes}.
404 Kill processes. Takes a PID or a process object and an optional
409 Eshell version of @code{list}. Allows you to create a list using Eshell
410 syntax, rather than Elisp syntax. For example, @samp{listify foo bar}
411 and @code{("foo" "bar")} both evaluate to @code{("foo" "bar")}.
415 Alias to Emacs's @code{locate} function, which simply runs the external
416 @command{locate} command and parses the results. @xref{Dired and `find', , , elisp}.
420 Run @command{make} through @code{compile}. @xref{Running Compilations under Emacs, , , elisp}.
424 Alias to Emacs's @code{occur}. @xref{Other Search-and-Loop Commands, , , elisp}.
428 Print the arguments separated by newlines.
432 This command changes the current working directory. Usually, it is
433 invoked as @samp{cd foo} where @file{foo} is the new working directory.
434 But @command{cd} knows about a few special arguments:
436 When it receives no argument at all, it changes to the home directory.
438 Giving the command @samp{cd -} changes back to the previous working
439 directory (this is the same as @samp{cd $-}).
441 The command @samp{cd =} shows the directory stack. Each line is
444 With @samp{cd =foo}, Eshell searches the directory stack for a directory
445 matching the regular expression @samp{foo} and changes to that
448 With @samp{cd -42}, you can access the directory stack by number.
454 Uses TRAMP's @command{su} or @command{sudo} method to run a command via
455 @command{su} or @command{sudo}.
459 @section Built-in variables
460 Eshell knows a few built-in variables:
466 This variable always contains the current working directory.
470 This variable always contains the previous working directory (the
471 current working directory from before the last @code{cd} command).
475 It refers to the last argument of the last command.
479 This is the result of the last command. In case of an external
480 command, it is @code{t} or @code{nil}.
484 This variable contains the exit code of the last command (0 or 1 for
485 Lisp functions, based on successful completion).
491 Since Eshell is just an Emacs REPL@footnote{Read-Eval-Print Loop}, it
492 does not have its own scope, and simply stores variables the same you
493 would in an Elisp program. Eshell provides a command version of
494 @code{setq} for convenience.
499 Aliases are commands that expand to a longer input line. For example,
500 @command{ll} is a common alias for @code{ls -l}, and would be defined
501 with the command invocation @samp{alias ll ls -l}; with this defined,
502 running @samp{ll foo} in Eshell will actually run @samp{ls -l foo}.
503 Aliases defined (or deleted) by the @command{alias} command are
504 automatically written to the file named by @var{eshell-aliases-file},
505 which you can also edit directly (although you will have to manually
511 The @samp{history} command shows all commands kept in the history ring
512 as numbered list. If the history ring contains
513 @code{eshell-history-size} commands, those numbers change after every
514 command invocation, therefore the @samp{history} command shall be
515 applied before using the expansion mechanism with history numbers.
517 The n-th entry of the history ring can be applied with the @samp{!n}
518 command. If @code{n} is negative, the entry is counted from the end
521 @samp{!foo} expands to the last command beginning with @code{foo}, and
522 @samp{!?foo} to the last command containing @code{foo}. The n-th
523 argument of the last command beginning with @code{foo} is accessible
526 The history ring is loaded from a file at the start of every session,
527 and written back to the file at the end of every session. The file path
528 is specified in @var{eshell-history-file-name}. Unlike other shells,
529 such as Bash, Eshell can not be configured to keep a history ring of a
530 different size than that of the history file.
532 Since the default buffer navigation and searching key-bindings are
533 still present in the Eshell buffer, the commands for history
534 navigation and searching are bound to different keys:
543 Previous and next history line. If there is anything on the input
544 line when you run these commands, they will instead jump to the
545 precious or next line that begins with that string.
550 Eshell uses the pcomplete package for programmable completion, similar
551 to that of other command shells. Argument completion differs depending
552 on the preceding command: for example, possible completions for
553 @command{rmdir} are only directories, while @command{rm} completions can
554 be directories @emph{and} files. Eshell provides predefined completions
555 for the built-in functions and some common external commands, and you
556 can define your own for any command.
558 Eshell completion also works for lisp forms and glob patterns. If the
559 point is on a lisp form, then @key{TAB} will behave similarly to completion
560 in @code{elisp-mode} and @code{lisp-interaction-mode}. For glob
561 patterns, If there are few enough possible completions of the patterns,
562 they will be cycled when @key{TAB} is pressed, otherwise it will be removed
563 from the input line and the possible completions will be listed.
565 If you want to see the entire list of possible completions when it's
566 below the cycling threshold, press @kbd{M-?}.
568 @subsection pcomplete
569 Pcomplete, short for programmable completion, is the completion
570 library originally written for Eshell, but usable for command
571 completion@footnote{Command completion as opposed to code completion,
572 which is a beyond the scope of pcomplete.} in other modes.
574 Completions are defined as functions (with @code{defun}) named
575 @code{pcomplete/COMMAND}, where @code{COMMAND} is the name of the
576 command for which this function provides completions; you can also name
577 the function @code{pcomplete/MAJOR-MODE/COMMAND} to define completions
578 for a specific major mode.
581 @section @code{for} loop
582 Because Eshell commands can not (easily) be combined with lisp forms,
583 Eshell provides a command-oriented @command{for}-loop for convenience.
584 The syntax is as follows:
587 @code{for VAR in TOKENS @{ command invocation(s) @}}
590 where @samp{TOKENS} is a space-separated sequence of values of
591 @var{VAR} for each iteration. This can even be the output of a
592 command if @samp{TOKENS} is replaced with @samp{@{ command invocation @}}.
597 @fnindex eshell-source-file
598 You can run Eshell scripts much like scripts for other shells; the main
599 difference is that since Eshell is not a system command, you have to run
600 it from within Emacs. An Eshell script is simply a file containing a
601 sequence of commands, as with almost any other shell script. Scripts
602 are invoked from Eshell with @command{source}, or from anywhere in Emacs
603 with @code{eshell-source-file}.
606 If you wish to load a script into your @emph{current} environment,
607 rather than in a subshell, use the @code{.} command.
611 Expansion in a command shell is somewhat like macro expansion in macro
612 parsers (such as @command{cpp} and @command{m4}), but in a command
613 shell, they are less often used for constants, and usually for using
614 variables and string manipulation.@footnote{Eshell has no
615 string-manipulation expansions because the Elisp library already
616 provides many functions for this.} For example, @code{$var} on a line
617 expands to the value of the variable @code{var} when the line is
618 executed. Expansions are usually passed as arguments, but may also be
619 used as commands.@footnote{e.g. Entering just @samp{$var} at the prompt
620 is equivalent to entering the value of @code{var} at the prompt.}
623 * Dollars Expansion::
627 @node Dollars Expansion
628 @section Dollars Expansion
629 Eshell has different @code{$} expansion syntax from other shells. There
630 are some similarities, but don't let these lull you into a false sense
636 Expands to the value bound to @code{var}. This is the main way to use
637 variables in command invocations.
640 Expands to the length of the value bound to @code{var}. Raises an error
641 if the value is not a sequence (@pxref{Sequences Arrays and Vectors, Sequences, , elisp}).
644 Expands to the result of evaluating the S-expression @code{(lisp)}. On
645 its own, this is identical to just @code{(lisp)}, but with the @code{$},
646 it can be used in a string, such as @samp{/some/path/$(lisp).txt}.
649 Returns the output of @command{command}, which can be any valid Eshell
650 command invocation, and may even contain expansions.
653 Expands to the @code{i}th element of the value bound to @code{var}. If
654 the value is a string, it will be split at whitespace to make it a list.
655 Again, raises an error if the value is not a sequence.
658 As above, but now splitting occurs at the colon character.
661 As above, but instead of returning just a string, it now returns a list
662 of two strings. If the result is being interpolated into a larger
663 string, this list will be flattened into one big string, with each
664 element separated by a space.
667 Separate on backslash characters. Actually, the first argument -- if it
668 doesn't have the form of a number, or a plain variable name -- can be
669 any regular expression. So to split on numbers, use @samp{$var["[0-9]+" 10 20]}.
672 Calls @code{assoc} on @code{var} with @code{"hello"}, expecting it to be
673 an alist (@pxref{Association List Type, Association Lists, , elisp}).
676 Returns the length of the cdr of the element of @code{var} who car is equal
683 Eshell's globbing syntax is very similar to that of Zsh. Users coming
684 from Bash can still use Bash-style globbing, as there are no
685 incompatibilities. Most globbing is pattern-based expansion, but there
686 is also predicate-based expansion. See @ref{Filename Generation, , , zsh}
687 for full syntax. To customize the syntax and behaviour of globbing in
688 Eshell see the Customize@footnote{@xref{Customization Settings, Customize, , elisp}.}
689 groups ``eshell-glob'' and ``eshell-pred''.
692 @chapter Input/Output
693 Since Eshell does not communicate with a terminal like most command
694 shells, IO is a little different. If you try to run programs from
695 within Eshell that are not line-oriented, such as programs that use
696 ncurses, you will just get garbage output, since the Eshell buffer is
697 not a terminal emulator. Eshell solves this problem by running
698 specified commands in Emacs's terminal emulator; to let Eshell know
699 which commands need to be run in a terminal, add them to the list
700 @var{eshell-visual-commands}.
702 Redirection is mostly the same in Eshell as it is in other command
703 shells. The output redirection operators @code{>} and @code{>>} as well
704 as pipes are supported, but there is not yet any support for input
705 redirection. Output can also be redirected to Elisp functions, using
708 @var{eshell-virtual-targets} is a list of mappings of virtual device
709 names to functions. Eshell comes with two virtual devices:
710 @file{/dev/kill}, which sends the text to the kill ring, and
711 @file{/dev/clip}, which sends text to the clipboard.
713 You can, of course, define your own virtual targets. They are defined
714 by adding a list of the form @code{("/dev/name" function mode)} to
715 @var{eshell-virtual-targets}. The first element is the device name;
716 @code{function} may be either a lambda or a function name. If
717 @code{mode} is nil, then the function is the output function; if it is
718 non-nil, then the function is passed the redirection mode as a
719 symbol--@code{overwrite}, @code{append}, or @code{insert}--and the
720 function is expected to return the output function.
722 The output function is called once on each line of output until
723 @code{nil} is passed, indicating end of output.
725 @node Extension modules
726 @chapter Extension modules
727 Eshell provides a facility for defining extension modules so that they
728 can be disabled and enabled without having to unload and reload them,
729 and to provide a common parent Customize group for the
730 modules.@footnote{ERC provides a similar module facility.} An Eshell
731 module is defined the same as any other library but one requirement: the
732 module must define a Customize@footnote{@xref{Customization Settings, Customize, , elisp}.}
733 group using @code{eshell-defgroup} (in place of @code{defgroup}) with
734 @code{eshell-module} as the parent group.@footnote{If the module has
735 no user-customizable options, then there is no need to define it as an
736 Eshell module.} You also need to load the following as shown:
750 * Directory handling::
753 * Terminal emulation::
756 @node Writing a module
757 @section Writing a module
760 @section Module testing
762 @node Directory handling
763 @section Directory handling
766 @section Key rebinding
768 @node Smart scrolling
769 @section Smart scrolling
771 @node Terminal emulation
772 @section Terminal emulation
775 @chapter Bugs and ideas
776 @cindex reporting bugs and ideas
777 @cindex bugs, how to report them
778 @cindex author, how to reach
779 @cindex email to the author
781 @cindex problems, list of common
785 If you find a bug or misfeature, don't hesitate to let me know! Send
786 email to @email{johnw@@gnu.org}. Feature requests should also be sent
787 there. I prefer discussing one thing at a time. If you find several
788 unrelated bugs, please report them separately.
790 If you have ideas for improvements, or if you have written some
791 extensions to this package, I would like to hear from you. I hope you
792 find this package useful!
794 Below is a complete list of known problems with Eshell version 2.4.2,
795 which is the version included with Emacs 22.
798 @item Documentation incomplete
800 @item Differentiate between aliases and functions
802 Allow for a Bash-compatible syntax, such as:
806 function arg () @{ blah $* @}
809 @item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt
811 In fact, piping to a process from a looping construct doesn't work in
812 general. If I change the call to @code{eshell-copy-handles} in
813 @code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems
814 to work, but the output occurs after the prompt is displayed. The whole
815 structured command thing is too complicated at present.
817 @item Error with @command{bc} in @code{eshell-test}
819 On some XEmacs system, the subprocess interaction test fails
820 inexplicably, although @command{bc} works fine at the command prompt.
822 @item Eshell does not delete @file{*Help*} buffers in XEmacs 21.1.8+
824 In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that
825 multiple instances of the @file{*Help*} buffer can exist.
827 @item Pcomplete sometimes gets stuck
829 You press @key{TAB}, but no completions appear, even though the
830 directory has matching files. This behavior is rare.
832 @item @samp{grep python $<rpm -qa>} doesn't work, but using @samp{*grep} does
834 This happens because the @code{grep} Lisp function returns immediately,
835 and then the asynchronous @command{grep} process expects to examine the
836 temporary file, which has since been deleted.
838 @item Problem with C-r repeating text
840 If the text @emph{before point} reads "./run", and you type @kbd{C-r r u
841 n}, it will repeat the line for every character typed.
843 @item Backspace doesn't scroll back after continuing (in smart mode)
845 Hitting space during a process invocation, such as @command{make}, will
846 cause it to track the bottom of the output; but backspace no longer
849 @item It's not possible to fully @code{unload-feature} Eshell
851 @item Menu support was removed, but never put back
853 @item Using C-p and C-n with rebind gets into a locked state
855 This happened a few times in Emacs 21, but has been unreproducible
858 @item If an interactive process is currently running, @kbd{M-!} doesn't work
860 @item Use a timer instead of @code{sleep-for} when killing child processes
862 @item Piping to a Lisp function is not supported
864 Make it so that the Lisp command on the right of the pipe is repeatedly
865 called with the input strings as arguments. This will require changing
866 @code{eshell-do-pipeline} to handle non-process targets.
868 @item Input redirection is not supported
872 @item Problem running @command{less} without arguments on Windows
874 The result in the Eshell buffer is:
877 Spawning child process: invalid argument
880 Also a new @command{less} buffer was created with nothing in it@dots{}
881 (presumably this holds the output of @command{less}).
883 If @command{less.exe} is invoked from the Eshell command line, the
884 expected output is written to the buffer.
886 Note that this happens on NT-Emacs 20.6.1 on Windows 2000. The term.el
887 package and the supplied shell both use the @command{cmdproxy} program
890 @item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp}
892 @item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be
894 @item @samp{mv @var{dir} @var{file}.tar} does not remove directories
896 This is because the tar option --remove-files doesn't do so. Should it
899 @item Bind @code{standard-output} and @code{standard-error}
901 This would be so that if a Lisp function calls @code{print}, everything
902 will happen as it should (albeit slowly).
904 @item When an extension module fails to load, @samp{cd /} gives a Lisp error
906 @item If a globbing pattern returns one match, should it be a list?
908 @item Make sure syntax table is correct in Eshell mode
910 So that @kbd{M-DEL} acts in a predictable manner, etc.
912 @item Allow all Eshell buffers to share the same history and list-dir
914 @item There is a problem with script commands that output to @file{/dev/null}
916 If a script file, somewhere in the middle, uses @samp{> /dev/null},
917 output from all subsequent commands is swallowed.
919 @item Split up parsing of text after @samp{$} in @file{esh-var.el}
921 Make it similar to the way that @file{esh-arg.el} is structured.
922 Then add parsing of @samp{$[?\n]}.
924 @item After pressing @kbd{M-RET}, redisplay before running the next command
926 @item Argument predicates and modifiers should work anywhere in a path
929 /usr/local/src/editors/vim $ vi **/CVS(/)/Root(.)
930 Invalid regexp: "Unmatched ( or \\("
933 With @command{zsh}, the glob above expands to all files named
934 @file{Root} in directories named @file{CVS}.
936 @item Typing @samp{echo $@{locate locate@}/bin<TAB>} results in a Lisp error
938 Perhaps it should interpolate all permutations, and make that the
939 globbing result, since otherwise hitting return here will result in
940 ``(list of filenames)/bin'', which is never valuable. Thus, one could
941 @command{cat} only C backup files by using @samp{ls $@{identity *.c@}~}.
942 In that case, having an alias command name @command{glob} for
943 @command{identity} would be useful.
945 @item Once symbolic mode is supported for @command{umask}, implement @command{chmod} in Lisp
947 @item Create @code{eshell-expand-file-name}
949 This would use a data table to transform things such as @samp{~+},
952 @item Abstract @file{em-smart.el} into @file{smart-scroll.el}
954 It only really needs: to be hooked onto the output filter and the
955 pre-command hook, and to have the input-end and input-start markers.
956 And to know whether the last output group was ``successful.''
958 @item Allow for fully persisting the state of Eshell
960 This would include: variables, history, buffer, input, dir stack, etc.
962 @item Implement D as an argument predicate
964 It means that files beginning with a dot should be included in the
967 @item A comma in a predicate list should mean OR
969 At the moment, this is not supported.
971 @item Error if a glob doesn't expand due to a predicate
973 An error should be generated only if @code{eshell-error-if-no-glob} is
976 @item @samp{(+ RET SPC TAB} does not cause @code{indent-according-to-mode} to occur
978 @item Create @code{eshell-auto-accumulate-list}
980 This is a list of commands for which, if the user presses @kbd{RET}, the
981 text is staged as the next Eshell command, rather than being sent to the
982 current interactive process.
984 @item Display file and line number if an error occurs in a script
986 @item @command{wait} doesn't work with process ids at the moment
988 @item Enable the direct-to-process input code in @file{em-term.el}
990 @item Problem with repeating @samp{echo $@{find /tmp@}}
992 With smart display active, if @kbd{RET} is held down, after a while it
993 can't keep up anymore and starts outputting blank lines. It only
994 happens if an asynchronous process is involved@dots{}
996 I think the problem is that @code{eshell-send-input} is resetting the
997 input target location, so that if the asynchronous process is not done
998 by the time the next @kbd{RET} is received, the input processor thinks
999 that the input is meant for the process; which, when smart display is
1000 enabled, will be the text of the last command line! That is a bug in
1003 In holding down @kbd{RET} while an asynchronous process is running,
1004 there will be a point in between termination of the process, and the
1005 running of @code{eshell-post-command-hook}, which would cause
1006 @code{eshell-send-input} to call @code{eshell-copy-old-input}, and then
1007 process that text as a command to be run after the process. Perhaps
1008 there should be a way of killing pending input between the death of the
1009 process, and the @code{post-command-hook}.
1011 @item Allow for a more aggressive smart display mode
1013 Perhaps toggled by a command, that makes each output block a smart
1016 @item Create more meta variables
1020 The reason for the failure of the last disk command, or the text of the
1024 A special associate array, which can take references of the form
1025 @samp{$=[REGEXP]}. It indexes into the directory ring.
1028 @item Eshell scripts can't execute in the background
1030 @item Support zsh's ``Parameter Expansion'' syntax, i.e. @samp{$@{@var{name}:-@var{val}@}}
1032 @item Write an @command{info} alias that can take arguments
1034 So that the user can enter @samp{info chmod}, for example.
1036 @item Create a mode @code{eshell-browse}
1038 It would treat the Eshell buffer as a outline. Collapsing the outline
1039 hides all of the output text. Collapsing again would show only the
1040 first command run in each directory
1042 @item Allow other revisions of a file to be referenced using @samp{file@{rev@}}
1044 This would be expanded by @code{eshell-expand-file-name} (see above).
1046 @item Print ``You have new mail'' when the ``Mail'' icon is turned on
1048 @item Implement @kbd{M-|} for Eshell
1050 @item Implement input redirection
1052 If it's a Lisp function, input redirection implies @command{xargs} (in a
1053 way@dots{}). If input redirection is added, also update the
1054 @code{file-name-quote-list}, and the delimiter list.
1056 @item Allow @samp{#<@var{word} @var{arg}>} as a generic syntax
1058 With the handling of @emph{word} specified by an
1059 @code{eshell-special-alist}.
1061 @item In @code{eshell-veal-using-options}, allow a @code{:complete} tag
1063 It would be used to provide completion rules for that command. Then the
1064 macro will automagically define the completion function.
1066 @item For @code{eshell-command-on-region}, apply redirections to the result
1068 So that @samp{+ > 'blah} would cause the result of the @code{+} (using
1069 input from the current region) to be inserting into the symbol
1072 If an external command is being invoked, the input is sent as standard
1073 input, as if a @samp{cat <region> |} had been invoked.
1075 If a Lisp command, or an alias, is invoked, then if the line has no
1076 newline characters, it is divided by whitespace and passed as arguments
1077 to the Lisp function. Otherwise, it is divided at the newline
1078 characters. Thus, invoking @code{+} on a series of numbers will add
1079 them; @code{min} would display the smallest figure, etc.
1081 @item Write @code{eshell-script-mode} as a minor mode
1083 It would provide syntax, abbrev, highlighting and indenting support like
1084 @code{emacs-lisp-mode} and @code{shell-mode}.
1086 @item In the history mechanism, finish the Bash-style support
1088 This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate
1091 @item Support the -n command line option for @command{history}
1093 @item Implement @command{fc} in Lisp
1095 @item Specifying a frame as a redirection target should imply the currently active window's buffer
1097 @item Implement @samp{>@var{func-or-func-list}}
1099 This would allow for an ``output translators'', that take a function to
1100 modify output with, and a target. Devise a syntax that works well with
1101 pipes, and can accommodate multiple functions (i.e., @samp{>'(upcase
1102 regexp-quote)} or @samp{>'upcase}).
1104 @item Allow Eshell to read/write to/from standard input and output
1106 This would be optional, rather than always using the Eshell buffer.
1107 This would allow it to be run from the command line (perhaps).
1109 @item Write a @command{help} command
1111 It would call subcommands with @option{--help}, or @option{-h} or
1112 @option{/?}, as appropriate.
1114 @item Implement @command{stty} in Lisp
1116 @item Support @command{rc}'s matching operator, e.g. @samp{~ (@var{list}) @var{regexp}}
1118 @item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list}
1120 Using @command{bg} on a process that is already in the background does
1121 nothing. Specifying redirection targets replaces (or adds) to the list
1124 @item Have @command{jobs} print only the processes for the current shell
1126 @item How can Eshell learn if a background process has requested input?
1128 @item Support @samp{2>&1} and @samp{>&} and @samp{2>} and @samp{|&}
1130 The syntax table for parsing these should be customizable, such that the
1131 user could change it to use rc syntax: @samp{>[2=1]}.
1133 @item Allow @samp{$_[-1]}, which would indicate the last element of the array
1135 @item Make @samp{$x[*]} equal to listing out the full contents of @samp{x}
1137 Return them as a list, so that @samp{$_[*]} is all the arguments of the
1140 @item Copy ANSI code handling from @file{term.el} into @file{em-term.el}
1142 Make it possible for the user to send char-by-char to the underlying
1143 process. Ultimately, I should be able to move away from using term.el
1144 altogether, since everything but the ANSI code handling is already part
1145 of Eshell. Then, things would work correctly on MS-Windows as well
1146 (which doesn't have @file{/bin/sh}, although @file{term.el} tries to use
1149 @item Make the shell spawning commands be visual
1151 That is, make (@command{su}, @command{bash}, @command{telnet},
1152 @command{rlogin}, @command{rsh}, etc.) be part of
1153 @code{eshell-visual-commands}. The only exception is if the shell is
1154 being used to invoke a single command. Then, the behavior should be
1155 based on what that command is.
1157 @item Create a smart viewing command named @command{open}
1159 This would search for some way to open its argument (similar to opening
1160 a file in the Windows Explorer).
1162 @item Alias @command{read} to be the same as @command{open}, only read-only
1164 @item Write a @command{tail} command which uses @code{view-file}
1166 It would move point to the end of the buffer, and then turns on
1167 auto-revert mode in that buffer at frequent intervals---and a
1168 @command{head} alias which assumes an upper limit of
1169 @code{eshell-maximum-line-length} characters per line.
1171 @item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search}
1175 This would run Emacs with the appropriate arguments to invoke Eshell
1176 only. That way, it could be listed as a login shell.
1178 @item Use an intangible @code{PS2} string for multi-line input prompts
1180 @item Auto-detect when a command is visual, by checking @code{TERMCAP} usage
1182 @item The first keypress after @kbd{M-x watson} triggers `eshell-send-input'
1184 @item Make @kbd{/} electric
1186 So that it automatically expands and corrects pathnames. Or make
1187 pathname completion for Pcomplete auto-expand @samp{/u/i/std<TAB>} to
1188 @samp{/usr/include/std<TAB>}.
1190 @item Write the @command{pushd} stack to disk along with @code{last-dir-ring}
1192 @item Add options to @code{eshell/cat} which would allow it to sort and uniq
1194 @item Implement @command{wc} in Lisp
1196 Add support for counting sentences, paragraphs, pages, etc.
1198 @item Once piping is added, implement @command{sort} and @command{uniq} in Lisp
1200 @item Implement @command{touch} in Lisp
1202 @item Implement @command{comm} in Lisp
1204 @item Implement an @command{epatch} command in Lisp
1206 This would call @code{ediff-patch-file}, or @code{ediff-patch-buffer},
1207 depending on its argument.
1209 @item Have an option such that @samp{ls -l} generates a dired buffer
1211 @item Write a version of @command{xargs} based on command rewriting
1213 That is, @samp{find X | xargs Y} would be indicated using @samp{Y
1214 $@{find X@}}. Maybe @code{eshell-do-pipelines} could be changed to
1215 perform this on-thy-fly rewriting.
1217 @item Write an alias for @command{less} that brings up a @code{view-mode} buffer
1219 Such that the user can press @key{SPC} and @key{DEL}, and then @key{q}
1220 to return to Eshell. It would be equivalent to:
1221 @samp{X > #<buffer Y>; view-buffer #<buffer Y>}.
1223 @item Make @code{eshell-mode} as much a full citizen as @code{shell-mode}
1225 Everywhere in Emacs where @code{shell-mode} is specially noticed, add
1226 @code{eshell-mode} there.
1228 @item Permit the umask to be selectively set on a @command{cp} target
1230 @item Problem using @kbd{M-x eshell} after using @code{eshell-command}
1232 If the first thing that I do after entering Emacs is to run
1233 @code{eshell-command} and invoke @command{ls}, and then use @kbd{M-x
1234 eshell}, it doesn't display anything.
1236 @item @kbd{M-RET} during a long command (using smart display) doesn't work
1238 Since it keeps the cursor up where the command was invoked.
1242 @node GNU Free Documentation License
1243 @appendix GNU Free Documentation License
1244 @include doclicense.texi
1247 @unnumbered Concept Index
1251 @node Function and Variable Index
1252 @unnumbered Function and Variable Index
1257 @unnumbered Command Index
1262 @unnumbered Key Index
1268 arch-tag: 776409ba-cb15-42b9-b2b6-d2bdc7ebad01