From b933f53818148676547dea7d587a9a6a3cd92d7e Mon Sep 17 00:00:00 2001 From: Earl Hyatt Date: Wed, 1 Dec 2021 20:47:18 -0500 Subject: [PATCH v1] Update the Info documentation of Eshell's built-in commands. * doc/misc/eshell.texi (Built-in commands): Add the remaining built-in Eshell commands to the list of built-ins. Expand some of the descriptions and mention user options affecting command behavior. Sort these commands in alphabetical order. --- doc/misc/eshell.texi | 338 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 313 insertions(+), 25 deletions(-) diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index fc2e3f3b11..4792ea9fc2 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -271,8 +271,30 @@ Built-ins external counterparts, and some have no external counterpart. Most of these will print a usage message when given the @code{--help} option. +In some cases, a built-in command's behavior can be configured via +user settings, some of which are mentioned below. For example, +certain commands have two user settings to allow them to overwrite +files without warning and to ensure that they always prompt before +overwriting files. If both settings are non-nil, the commands always +prompt. If both settings are nil (the default), the commands signal +an error. + +Several commands observe the value of +@code{eshell-default-target-is-dot}. If non-nil, then the default +target for the commands @command{cp}, @command{mv}, and @command{ln} +is the current directory. + +A few commands are wrappers for more niche Emacs features, and can be +loaded as part of the eshell-xtra module. @xref{Extension modules}. + @table @code +@item . +@cmindex . +Source an Eshell file in the current environment. This is not to be +confused with the command @command{source}, which sources a file in a +subshell environment. + @item addpath @cmindex addpath Adds a given path or set of paths to the PATH environment variable, or, @@ -282,26 +304,128 @@ Built-ins @cmindex alias Define an alias (@pxref{Aliases}). This adds it to the aliases file. +@item basename +@cmindex basename +Return a file name without its directory. + +@item cat +@cmindex cat +Concatenate file contents into standard output. If in a pipeline, or +if the file is not a regular file, directory, or symlink, then this +command reverts to the system's definition of @command{cat}. + +@item cd +@cmindex cd +This command changes the current working directory. Usually, it is +invoked as @samp{cd foo} where @file{foo} is the new working directory. +But @command{cd} knows about a few special arguments: + +When it receives no argument at all, it changes to the home directory. + +Giving the command @samp{cd -} changes back to the previous working +directory (this is the same as @samp{cd $-}). + +The command @samp{cd =} shows the directory stack. Each line is +numbered. + +With @samp{cd =foo}, Eshell searches the directory stack for a directory +matching the regular expression @samp{foo} and changes to that +directory. + +With @samp{cd -42}, you can access the directory stack by number. + +If @code{eshell-cd-shows-directory} is non-nil, @command{cd} will +report the directory it changes to. If +@code{eshell-list-files-after-cd} is non-nil, then @command{ls} is +called with any remaining arguments after changing directories. + @item clear @cmindex clear -Scrolls the contents of the eshell window out of sight, leaving a blank window. -If provided with an optional non-nil argument, the scrollback contents are -cleared instead. +Scrolls the contents of the Eshell window out of sight, leaving a +blank window. If provided with an optional non-nil argument, the +scrollback contents are cleared instead. + +@item clear-scrollback +@cmindex clear-scrollback +Clear the scrollback contents of the Eshell window. Unlike the +command @command{clear}, this command deletes content in the Eshell +buffer. + +@item cp +@cmindex cp +Copy a file to a new location or copy multiple files to the same +directory. + +If @code{eshell-cp-overwrite-files} is non-nil, then @command{cp} will +overwrite files without warning. If +@code{eshell-cp-interactive-query} is non-nil, then @command{cp} will +ask before overwriting anything. @item date @cmindex date -Similar to, but slightly different from, the GNU Coreutils +Print the current local time as a human-readable string. This command +is similar to, but slightly different from, the GNU Coreutils @command{date} command. @item define @cmindex define -Define a varalias. +Define a variable alias. @xref{Variable Aliases, , , elisp, The Emacs Lisp Reference Manual}. @item diff @cmindex diff -Use Emacs's internal @code{diff} (not to be confused with -@code{ediff}). @xref{Comparing Files, , , emacs, The GNU Emacs Manual}. +Compare files using Emacs's internal @code{diff} (not to be confused +with @code{ediff}). @xref{Comparing Files, , , emacs, The GNU Emacs +Manual}. + +If @code{eshell-plain-diff-behavior} is non-nil, then this command +does not use Emacs's internal @code{diff}. This is the same as using +@samp{alias diff '*diff $*'}. + +@item dirname +@cmindex dirname +Return the directory component of a file name. + +@item dirs +@cmindex dirs +Prints the directory stack. Directories can be added or removed from +the stack using the commands @command{pushd} and @command{popd}, +respectively. + +@item du +@cmindex du +Summarize disk usage for each file. + +@item echo +@cmindex echo +Echos its input. If @code{eshell-plain-echo-behavior} is non-nil, +@command{echo} will try to behave more like a plain shell's +@command{echo}. + +@item env +@cmindex env +Prints the current environment variables. Unlike in Bash, this +command does not yet support running commands with a modified +environment. + +@item exit +@cmindex exit +Exit Eshell and save the history. By default, this command kills the +Eshell buffer, but if @code{eshell-kill-on-exit} is nil, then the +buffer is merely buried instead. + +@item export +@cmindex export +Set environment variables using input like Bash's @command{export}, as +in @samp{export @var{var1}=@var{val1} @var{var2}=@var{val2} @dots{}}. + +@item expr +@cmindex expr +An implementation of @command{expr} using the Calc package. +@xref{Top,,, calc, The GNU Emacs Calculator}. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. @item grep @cmindex grep @@ -313,13 +437,35 @@ Built-ins @cmindex fgrep @itemx glimpse @cmindex glimpse -The @command{grep} commands are compatible with GNU @command{grep}, but -use Emacs's internal @code{grep} instead. +The @command{grep} commands are compatible with GNU @command{grep}, +but use Emacs's internal @code{grep} instead. +@xref{Grep Searching, , , emacs, The GNU Emacs Manual}. + +If @code{eshell-plain-grep-behavior} is non-nil, then these commands +do not use Emacs's internal @code{grep}. This is the same as using +@samp{alias grep '*grep $*'}, though this setting applies to all of +the built-in commands for which you would need to create a separate +alias. + +@item history +@cmindex history +Prints Eshell's input history. With a numeric argument @var{N}, this +command prints the @var{N} most recent items in the history. @item info @cmindex info -Same as the external @command{info} command, but uses Emacs's internal -Info reader. +Browse the available Info documentation. This command is the same as +the external @command{info} command, but uses Emacs's internal Info +reader. +@xref{Misc Help, , , emacs, The GNU Emacs Manual}. + +@item intersection +@cmindex intersection +A wrapper around the function @code{cl-intersection}. This command +can be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. @item jobs @cmindex jobs @@ -337,46 +483,146 @@ Built-ins syntax, rather than Elisp syntax. For example, @samp{listify foo bar} and @code{("foo" "bar")} both evaluate to @code{("foo" "bar")}. +@item ln +@cmindex ln +Create links to files. + +If @code{eshell-ln-overwrite-files} is non-nil, @command{ln} will +overwrite files without warning. If +@code{eshell-ln-interactive-query} is non-nil, then @command{ln} will +ask before overwriting files. + @item locate @cmindex locate Alias to Emacs's @code{locate} function, which simply runs the external @command{locate} command and parses the results. @xref{Dired and Find, , , emacs, The GNU Emacs Manual}. +If @code{eshell-plain-locate-behavior} is non-nil, then Emacs's +internal @code{locate} is not used. This is the same as using +@samp{alias locate '*locate $*'}. + +@item ls +@cmindex ls +Lists the contents of directories. + +If @code{eshell-ls-use-colors} is non-nil, the contents of a directory +is color-coded according to file type and status. These colors and +the regexps used to identify their corresponding files can be +customized via @samp{M-x customize-group RET eshell-ls RET}. + +The user option @code{eshell-ls-date-format} determines how the date +is displayed when using the @option{-l} option. The date is produced +using the function @code{format-time-string}. + +The user option @code{eshell-ls-initial-args} contains a list of +arguments to include with any call to @command{ls}. For example, you +can include the option @option{-h} to always use a more human-readable +format. + +The user option @code{eshell-ls-default-blocksize} determines the +default blocksize used when displaying file sizes with the option +@option{-s}. + @item make @cmindex make Run @command{make} through @code{compile} when run asynchronously (e.g., @samp{make &}). @xref{Compilation, , , emacs, The GNU Emacs Manual}. Otherwise call the external @command{make} command. +@item man +@cmindex man +Display Man pages using the Emacs @code{man} command. +@xref{Man Page, , , emacs, The GNU Emacs Manual}. + +@item mismatch +@cmindex mismatch +A wrapper around the function @code{cl-mismatch}. This command can be +used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item mkdir +@cmindex mkdir +Make new directories. + +@item mv +@cmindex mv +Move or rename files. + +If @code{eshell-mv-overwrite-files} is non-nil, @command{mv} will +overwrite files without warning. If +@code{eshell-mv-interactive-query} is non-nil, @command{mv} will +prompt before overwriting anything. + @item occur @cmindex occur Alias to Emacs's @code{occur}. @xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}. +@item popd +@cmindex popd +Pop a directory from the directory stack and switch to a another place +in the stack. + @item printnl @cmindex printnl Print the arguments separated by newlines. -@item cd -@cmindex cd -This command changes the current working directory. Usually, it is -invoked as @samp{cd foo} where @file{foo} is the new working directory. -But @command{cd} knows about a few special arguments: +@item pushd +@cmindex pushd +Change to a directory and push that directory onto the directory +stack. -When it receives no argument at all, it changes to the home directory. +If @code{eshell-pushd-dunique} is non-nil, then only unique +directories will be added to the stack. If +@code{eshell-pushd-dextract} is non-nil, then @samp{pushd +@var{n}} +will pop the @var{n}th directory to the top of the stack. -Giving the command @samp{cd -} changes back to the previous working -directory (this is the same as @samp{cd $-}). +@item pwd +@cmindex pwd +Prints the current working directory. -The command @samp{cd =} shows the directory stack. Each line is -numbered. +@item rm +@cmindex rm +Removes files, buffers, processes, or Emacs Lisp symbols, depending on +the argument. -With @samp{cd =foo}, Eshell searches the directory stack for a directory -matching the regular expression @samp{foo} and changes to that -directory. +If @code{eshell-rm-interactive-query} is non-nil, @command{rm} will +prompt before removing anything. If +@code{eshell-rm-removes-directories} is non-nil, then @command{rm} can +also remove directories. Otherwise, @command{rmdir} is required. -With @samp{cd -42}, you can access the directory stack by number. +@item rmdir +@cmindex rmdir +Removes directories if they are empty. + +@item set-difference +@cmindex set-difference +A wrapper around the function @code{cl-set-difference}. This command +can be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item set-exclusive-or +@cmindex set-exclusive-or +A wrapper around the function @code{cl-set-exclusive-or}. This +command can be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item setq +@cmindex setq +Set variable values, using the function @code{setq} like a command. + +@item source +@cmindex source +Source an Eshell file in a subshell environment. This is not to be +confused with the command @command{.}, which sources a file in the +current environment. @item su @cmindex su @@ -386,6 +632,48 @@ Built-ins to run a command via @command{su} or @command{sudo}. These commands are in the eshell-tramp module, which is disabled by default. + +@item substitute +@cmindex substitute +A wrapper around the function @code{cl-substitute}. This command can +be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item time +@cmindex time +Show the time elapsed during a command's execution. + +@item umask +@cmindex umask +Set or view the default file permissions for newly created files and +directories. + +@item union +@cmindex union +A wrapper around the function @code{cl-union}. This command can be +used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item unset +@cmindex unset +Unset an environment variable. + +@item wait +@cmindex wait +Wait until a process has successfully completed. + +@item which +@cmindex which +Identify a command and its location. + +@item whoami +@cmindex whoami +Print the current user. This Eshell version of @command{whoami} +supports Tramp. @end table @subsection Built-in variables -- 2.25.1