]> code.delx.au - gnu-emacs/blobdiff - doc/misc/eshell.texi
Add doclicense.texi dependency for doc/misc/Makefile targets
[gnu-emacs] / doc / misc / eshell.texi
index 5d6bd73a6cd1f7cefc70310204a437415c0d8aab..5011910033dc570af25b9f58845d20fe6ff823e6 100644 (file)
@@ -8,36 +8,26 @@
 @copying
 This manual is for Eshell, the Emacs shell.
 
 @copying
 This manual is for Eshell, the Emacs shell.
 
-Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
-2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+Copyright @copyright{} 1999--2012 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with no
 any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU
-Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License'' in the Emacs manual.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software.  Copies published by the Free
-Software Foundation raise funds for GNU development.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License.  If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
+and with the Back-Cover Texts as in (a) below.  A copy of the license
+is included in the section entitled ``GNU Free Documentation License''.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual.''
 @end quotation
 @end copying
 
 @end quotation
 @end copying
 
-@dircategory Emacs
+@dircategory Emacs misc features
 @direntry
 @direntry
-* Eshell: (eshell).     A command shell implemented in Emacs Lisp.
+* Eshell: (eshell).             A command shell implemented in Emacs Lisp.
 @end direntry
 
 @end direntry
 
-@setchapternewpage on
-
 @titlepage
 @sp 4
 @c The title is printed in a large font.
 @titlepage
 @sp 4
 @c The title is printed in a large font.
@@ -70,13 +60,15 @@ license to the document, as described in section 6 of the license.
 @node Top, What is Eshell?, (dir), (dir)
 @top Eshell
 
 @node Top, What is Eshell?, (dir), (dir)
 @top Eshell
 
-This manual documents Eshell, a shell-like command interpretor
+Eshell is a shell-like command interpreter
 implemented in Emacs Lisp.  It invokes no external processes except for
 those requested by the user.  It is intended to be a functional
 replacement for command shells such as @command{bash}, @command{zsh},
 @command{rc}, or @command{4dos}; since Emacs itself is capable of
 handling the sort of tasks accomplished by those tools.
 @c This manual is updated to release 2.4 of Eshell.
 implemented in Emacs Lisp.  It invokes no external processes except for
 those requested by the user.  It is intended to be a functional
 replacement for command shells such as @command{bash}, @command{zsh},
 @command{rc}, or @command{4dos}; since Emacs itself is capable of
 handling the sort of tasks accomplished by those tools.
 @c This manual is updated to release 2.4 of Eshell.
+
+@insertcopying
 @end ifnottex
 
 @menu
 @end ifnottex
 
 @menu
@@ -101,7 +93,7 @@ handling the sort of tasks accomplished by those tools.
 @cindex Eshell, what it is
 
 Eshell is a @dfn{command shell} written in Emacs Lisp.  Everything it
 @cindex Eshell, what it is
 
 Eshell is a @dfn{command shell} written in Emacs Lisp.  Everything it
-does, it uses Emacs' facilities to do.  This means that Eshell is as
+does, it uses Emacs's facilities to do.  This means that Eshell is as
 portable as Emacs itself.  It also means that cooperation with Lisp code
 is natural and seamless.
 
 portable as Emacs itself.  It also means that cooperation with Lisp code
 is natural and seamless.
 
@@ -340,6 +332,20 @@ This variable always contains the current working directory.
 This variable always contains the previous working directory (the
 current working directory from before the last @code{cd} command).
 
 This variable always contains the previous working directory (the
 current working directory from before the last @code{cd} command).
 
+@item $_
+@vindex $_
+It refers to the last argument of the last command.
+
+@item $$
+@vindex $$
+This is the result of the last command.  In case of an external
+command, it is @code{t} or @code{nil}.
+
+@item $?
+@vindex $?
+This variable contains the exit code of the last command (0 or 1 for
+Lisp functions, based on successful completion).
+
 @end table
 
 @node Scripts
 @end table
 
 @node Scripts
@@ -349,7 +355,30 @@ current working directory from before the last @code{cd} command).
 @node Built-ins
 @section Built-in commands
 
 @node Built-ins
 @section Built-in commands
 
-Here is a list of built-in commands that Eshell knows about:
+Several commands are built-in in Eshell.  In order to call the
+external variant of a built-in command @code{foo}, you could call
+@code{*foo}.  Usually, this should not be necessary.  You can check
+what will be applied by the @code{which} command:
+
+@example
+~ $ which ls
+eshell/ls is a compiled Lisp function in `em-ls.el'
+~ $ which *ls
+/bin/ls
+@end example
+
+If you want to discard a given built-in command, you could declare an
+alias, @ref{Aliases}.  Eample:
+
+@example
+~ $ which sudo
+eshell/sudo is a compiled Lisp function in `em-unix.el'
+~ $ alias sudo '*sudo $*'
+~ $ which sudo
+sudo is an alias, defined as "*sudo $*"
+@end example
+
+Some of the built-in commands have a special behavior in Eshell:
 
 @table @code
 
 
 @table @code
 
@@ -373,6 +402,48 @@ that directory.
 
 With @samp{cd -42}, you can access the directory stack by number.
 
 
 With @samp{cd -42}, you can access the directory stack by number.
 
+@item history
+@findex history
+The @samp{history} command shows all commands kept in the history ring
+as numbered list.  If the history ring contains
+@code{eshell-history-size} commands, those numbers change after every
+command invocation, therefore the @samp{history} command shall be
+applied before using the expansion mechanism with history numbers.
+
+The n-th entry of the history ring can be applied with the @samp{!n}
+command.  If @code{n} is negative, the entry is counted from the end
+of the history ring.
+
+@samp{!foo} expands to the last command beginning with @code{foo}, and
+@samp{!?foo} to the last command containing @code{foo}.  The n-th
+argument of the last command beginning with @code{foo} is accessible
+by @code{!foo:n}.
+
+@item su
+@findex su
+@itemx sudo
+@findex sudo
+@code{su} and @code{sudo} work as expected: they apply the following
+commands (@code{su}), or the command being an argument (@code{sudo})
+under the permissions of somebody else.
+
+This does not work only on
+the local host, but even on a remote one, when
+@code{default-directory} is a remote file name.  The necessary
+proxy configuration of Tramp is performed
+@ifinfo
+automatically, @ref{Multi-hops, , , tramp}.
+@end ifinfo
+@ifnotinfo
+automatically.
+@end ifnotinfo
+Example:
+
+@example
+~ $ cd /ssh:otherhost:/etc
+/ssh:user@@otherhost:/etc $ sudo find-file shadow
+@end example
+
 @end table
 
 
 @end table
 
 
@@ -536,7 +607,7 @@ scrolls back.
 
 @item Using C-p and C-n with rebind gets into a locked state
 
 
 @item Using C-p and C-n with rebind gets into a locked state
 
-This happened a few times in Emacs 21, but has been unreproducible
+This happened a few times in Emacs 21, but has been irreproducible
 since.
 
 @item If an interactive process is currently running, @kbd{M-!} doesn't work
 since.
 
 @item If an interactive process is currently running, @kbd{M-!} doesn't work
@@ -711,7 +782,7 @@ A special associate array, which can take references of the form
 
 @item Eshell scripts can't execute in the background
 
 
 @item Eshell scripts can't execute in the background
 
-@item Support zsh's ``Parameter Expansion'' syntax, i.e. @samp{$@{@var{name}:-@var{val}@}}
+@item Support zsh's ``Parameter Expansion'' syntax, i.e., @samp{$@{@var{name}:-@var{val}@}}
 
 @item Write an @command{info} alias that can take arguments
 
 
 @item Write an @command{info} alias that can take arguments
 
@@ -742,7 +813,7 @@ way@dots{}).  If input redirection is added, also update the
 With the handling of @emph{word} specified by an
 @code{eshell-special-alist}.
 
 With the handling of @emph{word} specified by an
 @code{eshell-special-alist}.
 
-@item In @code{eshell-veal-using-options}, allow a @code{:complete} tag
+@item In @code{eshell-eval-using-options}, allow a @code{:complete} tag
 
 It would be used to provide completion rules for that command.  Then the
 macro will automagically define the completion function.
 
 It would be used to provide completion rules for that command.  Then the
 macro will automagically define the completion function.
@@ -797,7 +868,7 @@ It would call subcommands with @option{--help}, or @option{-h} or
 
 @item Implement @command{stty} in Lisp
 
 
 @item Implement @command{stty} in Lisp
 
-@item Support @command{rc}'s matching operator, e.g. @samp{~ (@var{list}) @var{regexp}}
+@item Support @command{rc}'s matching operator, e.g., @samp{~ (@var{list}) @var{regexp}}
 
 @item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list}
 
 
 @item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list}
 
@@ -942,7 +1013,3 @@ Since it keeps the cursor up where the command was invoked.
 
 @printindex ky
 @bye
 
 @printindex ky
 @bye
-
-@ignore
-   arch-tag: 776409ba-cb15-42b9-b2b6-d2bdc7ebad01
-@end ignore