all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#68963: 30.0.50; [PATCH] Split Eshell built-in command documentation into subsections
@ 2024-02-07  0:02 Jim Porter
  2024-02-07  3:31 ` Eli Zaretskii
  0 siblings, 1 reply; 11+ messages in thread
From: Jim Porter @ 2024-02-07  0:02 UTC (permalink / raw)
  To: 68963

[-- Attachment #1: Type: text/plain, Size: 1155 bytes --]

Currently, the Eshell manual lists all the built-in commands in one 
section, which can make it hard to find the commands related to the 
topic you care about. Here's a patch to split this into subsections of 
various (loosely-defined) topics.

I welcome any suggestions about the division or the name of the 
subsections. For example, I split them into "Commands for Directories" 
and "Commands for Files", but an alternate scheme could be "Commands for 
Files and Directories" and "Commands for Changing the Current Directory".

Here's how I split the commands up in the patch, so you don't have to 
read through a huge diff:

# Commands for Directories
cd, dirs, du, ls, mkdir, popd, pushd, pwd, rmdir

# Commands for Files
cat, cp, diff, ln, mv, rm

# Commands for Searching
grep, agrep, egrep, fgrep, rgrep, glimpse, info, locate, man, occur

# Commands for Variables
env, export, set, setq, unset

# Commands for Using Other Commands
., addpath, alias, compile, jobs, kill, source, time, wait, which

# Miscellaneous Commands
basename, clear, clear-scrollback, date, dirname, echo, eshell-debug, 
exit, history, listify, make, printnl, umask, whoami

[-- Attachment #2: 0001-Split-Eshell-built-in-commands-documentation-into-su.patch --]
[-- Type: text/plain, Size: 37120 bytes --]

From dff38b933051b9a9a496814093b5984662cc2255 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Tue, 6 Feb 2024 15:53:17 -0800
Subject: [PATCH] Split Eshell built-in commands documentation into subsections

* doc/misc/eshell.texi (Built-ins): Move built-in commands to...
(Commands for Directories, Commands for Files, Commands for Searching)
(Commands for Variables, Commands for Using Other Commands)
(Miscellaneous Commands): ... these.
---
 doc/misc/eshell.texi | 925 ++++++++++++++++++++++---------------------
 1 file changed, 484 insertions(+), 441 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 5d3e5c7dbd6..c3d9eeae503 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -479,45 +479,19 @@ Built-ins
 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 . @var{file} [@var{argument}]@dots{}
-@cmindex .
-Source an Eshell script named @var{file} in the current environment,
-passing any @var{arguments} to the script (@pxref{Scripts}).  This is
-not to be confused with the command @command{source}, which sources a
-file in a subshell environment.
-
-@item addpath
-@itemx addpath [-b] @var{directory}@dots{}
-@cmindex addpath
-Adds each specified @var{directory} to the @code{$PATH} environment
-variable.  By default, this adds the directories to the end of
-@code{$PATH}, in the order they were passed on the command line; by
-passing @code{-b} or @code{--begin}, Eshell will instead add the
-directories to the beginning.
-
-With no directories, print the list of directories currently stored in
-@code{$PATH}.
-
-@item alias
-@itemx alias @var{name} [@var{command}]
-@cmindex alias
-Define an alias named @var{name} and expanding to @var{command},
-adding it to the aliases file (@pxref{Aliases}).  If @var{command} is
-omitted, delete the alias named @var{name}.  With no arguments at all,
-list all the currently-defined aliases.
-
-@item basename @var{filename}
-@cmindex basename
-Return @var{filename} without its directory.
+@menu
+* Commands for Directories::
+* Commands for Files::
+* Commands for Searching::
+* Commands for Variables::
+* Commands for Using Other Commands::
+* Miscellaneous Commands::
+* Defining New Built-in Commands::
+@end menu
 
-@item cat @var{file}@dots{}
-@cmindex cat
-Concatenate the contents of @var{file}s to standard output.  If in a
-pipeline, or if any of the files is not a regular file, directory, or
-symlink, then this command reverts to the system's definition of
-@command{cat}.
+@node Commands for Directories
+@subsection Commands for Directories
+@table @code
 
 @item cd
 @itemx cd @var{directory}
@@ -558,104 +532,6 @@ Built-ins
 @code{eshell-list-files-after-cd} is non-@code{nil}, then @command{ls}
 is called with any remaining arguments after changing directories.
 
-@item clear [@var{scrollback}]
-@cmindex clear
-Scrolls the contents of the Eshell window out of sight, leaving a
-blank window.  If @var{scrollback} is non-@code{nil}, the scrollback
-contents are cleared instead, as with @command{clear-scrollback}.
-
-@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 compile [-p | -i] [-m @var{mode-name}] @var{command}@dots{}
-@cmindex compile
-Run an external command, sending its output to a compilation buffer if
-the command would output to the screen and is not part of a pipeline
-or subcommand.
-
-With the @code{-p} or @code{--plain} options, always send the output
-to the Eshell buffer; similarly, with @code{-i} or
-@code{--interactive}, always send the output to a compilation buffer.
-You can also set the mode of the compilation buffer with @code{-m
-@var{mode-name}} or @code{--mode @var{mode-name}}.
-
-@command{compile} is particularly useful when defining aliases, so
-that interactively, the output shows up in a compilation buffer, but
-you can still pipe the output elsewhere if desired.  For example, if
-you have a grep-like command on your system, you might define an alias
-for it like so: @samp{alias mygrep 'compile --mode=grep-mode -- mygrep
-$*'}.
-
-@item cp [@var{option}@dots{}] @var{source} @var{dest}
-@item cp [@var{option}@dots{}] @var{source}@dots{} @var{directory}
-@cmindex cp
-Copy the file @var{source} to @var{dest} or @var{source} into
-@var{directory}.
-
-@vindex eshell-cp-overwrite-files
-@vindex eshell-cp-interactive-query
-If @code{eshell-cp-overwrite-files} is non-@code{nil}, then
-@command{cp} will overwrite files without warning.  If
-@code{eshell-cp-interactive-query} is non-@code{nil}, then
-@command{cp} will ask before overwriting anything.
-
-@command{cp} accepts the following options:
-
-@table @asis
-
-@item @code{-a}, @code{--archive}
-Equivalent to @code{--no-dereference --preserve --recursive}.
-
-@item @code{-d}, @code{--no-dereference}
-Don't dereference symbolic links when copying; instead, copy the link
-itself.
-
-@item @code{-f}, @code{--force}
-Never prompt for confirmation before copying a file.
-
-@item @code{-i}, @code{--interactive}
-Prompt for confirmation before copying a file if the target already
-exists.
-
-@item @code{-n}, @code{--preview}
-Run the command, but don't copy anything.  This is useful if you
-want to preview what would be removed when calling @command{cp}.
-
-@item @code{-p}, @code{--preserve}
-Attempt to preserve file attributes when copying.
-
-@item @code{-r}, @code{-R}, @code{--recursive}
-Copy any specified directories and their contents recursively.
-
-@item @code{-v}, @code{--verbose}
-Print the name of each file before copying it.
-
-@end table
-
-@item date [@var{specified-time} [@var{zone}]]
-@cmindex date
-Print the current local time as a human-readable string.  This command
-is an alias to the Emacs Lisp function @code{current-time-string}
-(@pxref{Time of Day,,, elisp, GNU Emacs Lisp Reference Manual}).
-
-@item diff [@var{option}]@dots{} @var{old} @var{new}
-@cmindex diff
-Compare the files @var{old} and @var{new} using Emacs's internal
-@code{diff} (not to be confused with @code{ediff}).  @xref{Comparing
-Files, , , emacs, The GNU Emacs Manual}.
-
-@vindex eshell-plain-diff-behavior
-If @code{eshell-plain-diff-behavior} is non-@code{nil}, then this
-command does not use Emacs's internal @code{diff}.  This is the same
-as using @samp{alias diff '*diff $@@*'}.
-
-@item dirname @var{filename}
-@cmindex dirname
-Return the directory component of @var{filename}.
-
 @item dirs
 @cmindex dirs
 Prints the directory stack.  Directories can be added or removed from
@@ -711,235 +587,58 @@ Built-ins
 
 @end table
 
-@item echo [-n | -N] [@var{arg}]@dots{}
-@cmindex echo
-Prints the value of each @var{arg}.  By default, this prints in a
-Lisp-friendly fashion (so that the value is useful to a Lisp command
-using the result of @command{echo} as an argument).  If a single
-argument is passed, @command{echo} prints that; if multiple arguments
-are passed, it prints a list of all the arguments; otherwise, it
-prints the empty string.
-
-@vindex eshell-plain-echo-behavior
-If @code{eshell-plain-echo-behavior} is non-@code{nil}, @command{echo}
-will try to behave more like a plain shell's @command{echo}, printing
-each argument as a string, separated by a space.
-
-You can control whether @command{echo} outputs a trailing newline
-using @code{-n} to disable the trailing newline (the default behavior)
-or @code{-N} to enable it (the default when
-@code{eshell-plain-echo-behavior} is non-@code{nil}).
+@item ls [@var{option}]@dots{} [@var{file}]@dots{}
+@cmindex ls
+List information about each @var{file}, including the contents of any
+specified directories.  If @var{file} is unspecified, list the
+contents of the current directory.
 
-@item env [@var{var}=@var{value}]@dots{} [@var{command}]@dots{}
-@cmindex env
-With no arguments, print the current environment variables.  If you
-pass arguments to this command, then @command{env} will execute the
-arguments as a command.  If you pass any initial arguments of the form
-@samp{@var{var}=@var{value}}, @command{env} will first set @var{var}
-to @var{value} before running the command.
+@vindex eshell-ls-initial-args
+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.
 
-@item eshell-debug [error | form | process]@dots{}
-@cmindex eshell-debug
-Toggle debugging information for Eshell itself.  You can pass this
-command one or more of the following arguments:
+@vindex eshell-ls-use-colors
+If @code{eshell-ls-use-colors} is non-@code{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 @w{@kbd{M-x customize-group @key{RET} eshell-ls
+@key{RET}}}.
 
-@itemize @bullet
+@command{ls} supports the following options:
 
-@item
-@code{error}, to enable/disable Eshell trapping errors when
-evaluating commands;
+@table @asis
 
-@item
-@code{form}, to show/hide Eshell command form manipulation in the
-buffer @code{*eshell last cmd*}; or
+@item @code{-a}, @code{--all}
+List all files, including ones starting with @samp{.}.
 
-@item
-@code{process}, to show/hide external process events in the buffer
-@code{*eshell last cmd*}.
+@item @code{-A}, @code{--almost-all}
+Like @code{--all}, but don't list the current directory (@file{.}) or
+the parent directory (@file{..}).
 
-@end itemize
+@item @code{-c}, @code{--by-ctime}
+Sort files by last status change time, with newest files first.
 
-@item exit
-@cmindex exit
-@vindex eshell-kill-on-exit
-Exit Eshell and save the history.  By default, this command kills the
-Eshell buffer, but if @code{eshell-kill-on-exit} is @code{nil}, then
-the buffer is merely buried instead.
+@item @code{-C}
+List entries by columns.
 
-@item export [@var{name}=@var{value}]@dots{}
-@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 @code{-d}, @code{--directory}
+List directory entries instead of their contents.
 
-@item grep [@var{arg}]@dots{}
-@cmindex grep
-@itemx agrep [@var{arg}]@dots{}
-@cmindex agrep
-@itemx egrep [@var{arg}]@dots{}
-@cmindex egrep
-@itemx fgrep [@var{arg}]@dots{}
-@cmindex fgrep
-@itemx rgrep [@var{arg}]@dots{}
-@cmindex rgrep
-@itemx glimpse [@var{arg}]@dots{}
-@cmindex glimpse
-The @command{grep} commands are compatible with GNU @command{grep},
-but open a compilation buffer in @code{grep-mode} instead.
-@xref{Grep Searching, , , emacs, The GNU Emacs Manual}.
+@item @code{-h}, @code{--human-readable}
+Print sizes in human-readable format, with binary prefixes (so 1 KB is
+1024 bytes).
 
-@vindex eshell-plain-grep-behavior
-If @code{eshell-plain-grep-behavior} is non-@code{nil}, then these
-commands do not use open a compilation buffer, instead printing output
-to Eshell's buffer.  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 @code{-H}, @code{--si}
+Print sizes in human-readable format, with decimal prefixes (so 1 KB
+is 1000 bytes).
 
-@item history [@var{n}]
-@itemx history [-arw] [@var{filename}]
-@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.
-Alternately, you can specify the following options:
+@item @code{-I@var{pattern}}, @code{--ignore=@var{pattern}}
+Don't list directory entries matching @var{pattern}.
 
-@table @asis
-
-@item @code{-a}, @code{--append}
-Append new history items to the history file.
-
-@item @code{-r}, @code{--read}
-Read history items from the history file and append them to the
-current shell's history.
-
-@item @code{-w}, @code{--write}
-Write the current history list to the history file.
-
-@end table
-
-@item info [@var{manual} [@var{item}]@dots{}]
-@cmindex info
-Browse the available Info documentation.  With no arguments, browse
-the top-level menu.  Otherwise, show the manual for @var{manual},
-selecting the menu entry for @var{item}.
-
-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 jobs
-@cmindex jobs
-List subprocesses of the Emacs process, if any, using the function
-@code{list-processes}.
-
-@item kill [-@var{signal}] [@var{pid} | @var{process}]
-@cmindex kill
-Kill processes.  Takes a PID or a process object and an optional
-@var{signal} specifier which can either be a number or a signal name.
-
-@item listify [@var{arg}]@dots{}
-@cmindex listify
-Return the arguments as a single list.  With a single argument, return
-it as-is if it's already a list, or otherwise wrap it in a list.  With
-multiple arguments, return a list of all of them.
-
-@item ln [@var{option}]@dots{} @var{target} [@var{link-name}]
-@itemx ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
-@cmindex ln
-Create a link to the specified @var{target} named @var{link-name} or
-create links to multiple @var{targets} in @var{directory}.
-
-@vindex eshell-ln-overwrite-files
-@vindex eshell-ln-interactive-query
-If @code{eshell-ln-overwrite-files} is non-@code{nil}, @command{ln}
-will overwrite files without warning.  If
-@code{eshell-ln-interactive-query} is non-@code{nil}, then
-@command{ln} will ask before overwriting files.
-
-@command{ln} accepts the following options:
-
-@table @asis
-
-@item @code{-f}, @code{--force}
-Never prompt for confirmation before linking a target.
-
-@item @code{-i}, @code{--interactive}
-Prompt for confirmation before linking to an item if the source
-already exists.
-
-@item @code{-n}, @code{--preview}
-Run the command, but don't move anything.  This is useful if you
-want to preview what would be linked when calling @command{ln}.
-
-@item @code{-s}, @code{--symbolic}
-Make symbolic links instead of hard links.
-
-@item @code{-v}, @code{--verbose}
-Print the name of each file before linking it.
-
-@end table
-
-@item locate @var{arg}@dots{}
-@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}.
-
-@vindex eshell-plain-locate-behavior
-If @code{eshell-plain-locate-behavior} is non-@code{nil}, then Emacs's
-internal @code{locate} is not used.  This is the same as using
-@samp{alias locate '*locate $@@*'}.
-
-@item ls [@var{option}]@dots{} [@var{file}]@dots{}
-@cmindex ls
-List information about each @var{file}, including the contents of any
-specified directories.  If @var{file} is unspecified, list the
-contents of the current directory.
-
-@vindex eshell-ls-initial-args
-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.
-
-@vindex eshell-ls-use-colors
-If @code{eshell-ls-use-colors} is non-@code{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 @w{@kbd{M-x customize-group @key{RET} eshell-ls
-@key{RET}}}.
-
-@command{ls} supports the following options:
-
-@table @asis
-
-@item @code{-a}, @code{--all}
-List all files, including ones starting with @samp{.}.
-
-@item @code{-A}, @code{--almost-all}
-Like @code{--all}, but don't list the current directory (@file{.}) or
-the parent directory (@file{..}).
-
-@item @code{-c}, @code{--by-ctime}
-Sort files by last status change time, with newest files first.
-
-@item @code{-C}
-List entries by columns.
-
-@item @code{-d}, @code{--directory}
-List directory entries instead of their contents.
-
-@item @code{-h}, @code{--human-readable}
-Print sizes in human-readable format, with binary prefixes (so 1 KB is
-1024 bytes).
-
-@item @code{-H}, @code{--si}
-Print sizes in human-readable format, with decimal prefixes (so 1 KB
-is 1000 bytes).
-
-@item @code{-I@var{pattern}}, @code{--ignore=@var{pattern}}
-Don't list directory entries matching @var{pattern}.
-
-@item @code{-k}, @code{--kilobytes}
-Print sizes as 1024-byte kilobytes.
+@item @code{-k}, @code{--kilobytes}
+Print sizes as 1024-byte kilobytes.
 
 @vindex eshell-ls-date-format
 @item @code{-l}
@@ -990,60 +689,11 @@ Built-ins
 
 @end table
 
-@item make [@var{arg}]@dots{}
-@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 [@var{arg}]@dots{}
-@cmindex man
-Display Man pages using the Emacs @code{man} command.
-@xref{Man Page, , , emacs, The GNU Emacs Manual}.
-
 @item mkdir [-p] @var{directory}@dots{}
 @cmindex mkdir
 Make new directories.  With @code{-p} or @code{--parents},
 automatically make any necessary parent directories as well.
 
-@item mv [@var{option}]@dots{} @var{source} @var{dest}
-@itemx mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
-@cmindex mv
-Rename the file @var{source} to @var{dest} or move @var{source} into
-@var{directory}.
-
-@vindex eshell-mv-overwrite-files
-@vindex eshell-mv-interactive-query
-If @code{eshell-mv-overwrite-files} is non-@code{nil}, @command{mv}
-will overwrite files without warning.  If
-@code{eshell-mv-interactive-query} is non-@code{nil}, @command{mv}
-will prompt before overwriting anything.
-
-@command{mv} accepts the following options:
-
-@table @asis
-
-@item @code{-f}, @code{--force}
-Never prompt for confirmation before moving an item.
-
-@item @code{-i}, @code{--interactive}
-Prompt for confirmation before moving an item if the target already
-exists.
-
-@item @code{-n}, @code{--preview}
-Run the command, but don't move anything.  This is useful if you
-want to preview what would be moved when calling @command{mv}.
-
-@item @code{-v}, @code{--verbose}
-Print the name of each item before moving it.
-
-@end table
-
-@item occur @var{regexp} [@var{nlines}]
-@cmindex occur
-Alias to Emacs's @code{occur}.
-@xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}.
-
 @item popd
 @item popd +@var{n}
 @cmindex popd
@@ -1062,10 +712,6 @@ Built-ins
 
 @end table
 
-@item printnl [@var{arg}]@dots{}
-@cmindex printnl
-Print all the @var{arg}s separated by newlines.
-
 @item pushd
 @itemx pushd @var{directory}
 @itemx pushd +@var{n}
@@ -1102,44 +748,262 @@ Built-ins
 @cmindex pwd
 Prints the current working directory.
 
-@item rm [@var{option}]@dots{} @var{item}@dots{}
-@cmindex rm
-Removes files, buffers, processes, or Emacs Lisp symbols, depending on
-the type of each @var{item}.
+@item rmdir @var{directory}@dots{}
+@cmindex rmdir
+Removes directories if they are empty.
 
-@vindex eshell-rm-interactive-query
-@vindex eshell-rm-removes-directories
-If @code{eshell-rm-interactive-query} is non-@code{nil}, @command{rm}
-will prompt before removing anything.  If
-@code{eshell-rm-removes-directories} is non-@code{nil}, then
-@command{rm} can also remove directories.  Otherwise, @command{rmdir}
-is required.
+@end table
 
-@command{rm} accepts the following options:
+@node Commands for Files
+@subsection Commands for Files
+@table @code
+
+@item cat @var{file}@dots{}
+@cmindex cat
+Concatenate the contents of @var{file}s to standard output.  If in a
+pipeline, or if any of the files is not a regular file, directory, or
+symlink, then this command reverts to the system's definition of
+@command{cat}.
+
+@item cp [@var{option}@dots{}] @var{source} @var{dest}
+@item cp [@var{option}@dots{}] @var{source}@dots{} @var{directory}
+@cmindex cp
+Copy the file @var{source} to @var{dest} or @var{source} into
+@var{directory}.
+
+@vindex eshell-cp-overwrite-files
+@vindex eshell-cp-interactive-query
+If @code{eshell-cp-overwrite-files} is non-@code{nil}, then
+@command{cp} will overwrite files without warning.  If
+@code{eshell-cp-interactive-query} is non-@code{nil}, then
+@command{cp} will ask before overwriting anything.
+
+@command{cp} accepts the following options:
 
 @table @asis
 
+@item @code{-a}, @code{--archive}
+Equivalent to @code{--no-dereference --preserve --recursive}.
+
+@item @code{-d}, @code{--no-dereference}
+Don't dereference symbolic links when copying; instead, copy the link
+itself.
+
 @item @code{-f}, @code{--force}
-Never prompt for confirmation before removing an item.
+Never prompt for confirmation before copying a file.
 
 @item @code{-i}, @code{--interactive}
-Prompt for confirmation before removing each item.
+Prompt for confirmation before copying a file if the target already
+exists.
 
 @item @code{-n}, @code{--preview}
-Run the command, but don't remove anything.  This is useful if you
-want to preview what would be removed when calling @command{rm}.
+Run the command, but don't copy anything.  This is useful if you
+want to preview what would be removed when calling @command{cp}.
+
+@item @code{-p}, @code{--preserve}
+Attempt to preserve file attributes when copying.
 
 @item @code{-r}, @code{-R}, @code{--recursive}
-Remove any specified directories and their contents recursively.
+Copy any specified directories and their contents recursively.
 
 @item @code{-v}, @code{--verbose}
-Print the name of each item before removing it.
+Print the name of each file before copying it.
 
 @end table
 
-@item rmdir @var{directory}@dots{}
-@cmindex rmdir
-Removes directories if they are empty.
+@item diff [@var{option}]@dots{} @var{old} @var{new}
+@cmindex diff
+Compare the files @var{old} and @var{new} using Emacs's internal
+@code{diff} (not to be confused with @code{ediff}).  @xref{Comparing
+Files, , , emacs, The GNU Emacs Manual}.
+
+@vindex eshell-plain-diff-behavior
+If @code{eshell-plain-diff-behavior} is non-@code{nil}, then this
+command does not use Emacs's internal @code{diff}.  This is the same
+as using @samp{alias diff '*diff $@@*'}.
+
+@item ln [@var{option}]@dots{} @var{target} [@var{link-name}]
+@itemx ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
+@cmindex ln
+Create a link to the specified @var{target} named @var{link-name} or
+create links to multiple @var{targets} in @var{directory}.
+
+@vindex eshell-ln-overwrite-files
+@vindex eshell-ln-interactive-query
+If @code{eshell-ln-overwrite-files} is non-@code{nil}, @command{ln}
+will overwrite files without warning.  If
+@code{eshell-ln-interactive-query} is non-@code{nil}, then
+@command{ln} will ask before overwriting files.
+
+@command{ln} accepts the following options:
+
+@table @asis
+
+@item @code{-f}, @code{--force}
+Never prompt for confirmation before linking a target.
+
+@item @code{-i}, @code{--interactive}
+Prompt for confirmation before linking to an item if the source
+already exists.
+
+@item @code{-n}, @code{--preview}
+Run the command, but don't move anything.  This is useful if you
+want to preview what would be linked when calling @command{ln}.
+
+@item @code{-s}, @code{--symbolic}
+Make symbolic links instead of hard links.
+
+@item @code{-v}, @code{--verbose}
+Print the name of each file before linking it.
+
+@end table
+
+@item mv [@var{option}]@dots{} @var{source} @var{dest}
+@itemx mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
+@cmindex mv
+Rename the file @var{source} to @var{dest} or move @var{source} into
+@var{directory}.
+
+@vindex eshell-mv-overwrite-files
+@vindex eshell-mv-interactive-query
+If @code{eshell-mv-overwrite-files} is non-@code{nil}, @command{mv}
+will overwrite files without warning.  If
+@code{eshell-mv-interactive-query} is non-@code{nil}, @command{mv}
+will prompt before overwriting anything.
+
+@command{mv} accepts the following options:
+
+@table @asis
+
+@item @code{-f}, @code{--force}
+Never prompt for confirmation before moving an item.
+
+@item @code{-i}, @code{--interactive}
+Prompt for confirmation before moving an item if the target already
+exists.
+
+@item @code{-n}, @code{--preview}
+Run the command, but don't move anything.  This is useful if you
+want to preview what would be moved when calling @command{mv}.
+
+@item @code{-v}, @code{--verbose}
+Print the name of each item before moving it.
+
+@end table
+
+@item rm [@var{option}]@dots{} @var{item}@dots{}
+@cmindex rm
+Removes files, buffers, processes, or Emacs Lisp symbols, depending on
+the type of each @var{item}.
+
+@vindex eshell-rm-interactive-query
+@vindex eshell-rm-removes-directories
+If @code{eshell-rm-interactive-query} is non-@code{nil}, @command{rm}
+will prompt before removing anything.  If
+@code{eshell-rm-removes-directories} is non-@code{nil}, then
+@command{rm} can also remove directories.  Otherwise, @command{rmdir}
+is required.
+
+@command{rm} accepts the following options:
+
+@table @asis
+
+@item @code{-f}, @code{--force}
+Never prompt for confirmation before removing an item.
+
+@item @code{-i}, @code{--interactive}
+Prompt for confirmation before removing each item.
+
+@item @code{-n}, @code{--preview}
+Run the command, but don't remove anything.  This is useful if you
+want to preview what would be removed when calling @command{rm}.
+
+@item @code{-r}, @code{-R}, @code{--recursive}
+Remove any specified directories and their contents recursively.
+
+@item @code{-v}, @code{--verbose}
+Print the name of each item before removing it.
+
+@end table
+
+@end table
+
+@node Commands for Searching
+@subsection Commands for Searching
+@table @code
+
+@item grep [@var{arg}]@dots{}
+@cmindex grep
+@itemx agrep [@var{arg}]@dots{}
+@cmindex agrep
+@itemx egrep [@var{arg}]@dots{}
+@cmindex egrep
+@itemx fgrep [@var{arg}]@dots{}
+@cmindex fgrep
+@itemx rgrep [@var{arg}]@dots{}
+@cmindex rgrep
+@itemx glimpse [@var{arg}]@dots{}
+@cmindex glimpse
+The @command{grep} commands are compatible with GNU @command{grep},
+but open a compilation buffer in @code{grep-mode} instead.
+@xref{Grep Searching, , , emacs, The GNU Emacs Manual}.
+
+@vindex eshell-plain-grep-behavior
+If @code{eshell-plain-grep-behavior} is non-@code{nil}, then these
+commands do not use open a compilation buffer, instead printing output
+to Eshell's buffer.  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 info [@var{manual} [@var{item}]@dots{}]
+@cmindex info
+Browse the available Info documentation.  With no arguments, browse
+the top-level menu.  Otherwise, show the manual for @var{manual},
+selecting the menu entry for @var{item}.
+
+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 locate @var{arg}@dots{}
+@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}.
+
+@vindex eshell-plain-locate-behavior
+If @code{eshell-plain-locate-behavior} is non-@code{nil}, then Emacs's
+internal @code{locate} is not used.  This is the same as using
+@samp{alias locate '*locate $@@*'}.
+
+@item man [@var{arg}]@dots{}
+@cmindex man
+Display Man pages using the Emacs @code{man} command.
+@xref{Man Page, , , emacs, The GNU Emacs Manual}.
+
+@item occur @var{regexp} [@var{nlines}]
+@cmindex occur
+Alias to Emacs's @code{occur}.
+@xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}.
+
+@end table
+
+@node Commands for Variables
+@subsection Commands for Variables
+@table @code
+
+@item env [@var{var}=@var{value}]@dots{} [@var{command}]@dots{}
+@cmindex env
+With no arguments, print the current environment variables.  If you
+pass arguments to this command, then @command{env} will execute the
+arguments as a command.  If you pass any initial arguments of the form
+@samp{@var{var}=@var{value}}, @command{env} will first set @var{var}
+to @var{value} before running the command.
+
+@item export [@var{name}=@var{value}]@dots{}
+@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 set [@var{var} @var{value}]@dots{}
 @cmindex set
@@ -1154,6 +1018,74 @@ Built-ins
 Set variable values, using the function @code{setq} like a command
 (@pxref{Setting Variables,,, elisp, GNU Emacs Lisp Reference Manual}).
 
+@item unset [@var{var}]@dots{}
+@cmindex unset
+Unset one or more variables.  As with @command{set}, the value of
+@var{var} can be a symbol, in which case it refers to a Lisp variable,
+or a string, referring to an environment variable.
+
+@end table
+
+@node Commands for Using Other Commands
+@subsection Commands for Using Other Commands
+@table @code
+
+@item . @var{file} [@var{argument}]@dots{}
+@cmindex .
+Source an Eshell script named @var{file} in the current environment,
+passing any @var{arguments} to the script (@pxref{Scripts}).  This is
+not to be confused with the command @command{source}, which sources a
+file in a subshell environment.
+
+@item addpath
+@itemx addpath [-b] @var{directory}@dots{}
+@cmindex addpath
+Adds each specified @var{directory} to the @code{$PATH} environment
+variable.  By default, this adds the directories to the end of
+@code{$PATH}, in the order they were passed on the command line; by
+passing @code{-b} or @code{--begin}, Eshell will instead add the
+directories to the beginning.
+
+With no directories, print the list of directories currently stored in
+@code{$PATH}.
+
+@item alias
+@itemx alias @var{name} [@var{command}]
+@cmindex alias
+Define an alias named @var{name} and expanding to @var{command},
+adding it to the aliases file (@pxref{Aliases}).  If @var{command} is
+omitted, delete the alias named @var{name}.  With no arguments at all,
+list all the currently-defined aliases.
+
+@item compile [-p | -i] [-m @var{mode-name}] @var{command}@dots{}
+@cmindex compile
+Run an external command, sending its output to a compilation buffer if
+the command would output to the screen and is not part of a pipeline
+or subcommand.
+
+With the @code{-p} or @code{--plain} options, always send the output
+to the Eshell buffer; similarly, with @code{-i} or
+@code{--interactive}, always send the output to a compilation buffer.
+You can also set the mode of the compilation buffer with @code{-m
+@var{mode-name}} or @code{--mode @var{mode-name}}.
+
+@command{compile} is particularly useful when defining aliases, so
+that interactively, the output shows up in a compilation buffer, but
+you can still pipe the output elsewhere if desired.  For example, if
+you have a grep-like command on your system, you might define an alias
+for it like so: @samp{alias mygrep 'compile --mode=grep-mode -- mygrep
+$*'}.
+
+@item jobs
+@cmindex jobs
+List subprocesses of the Emacs process, if any, using the function
+@code{list-processes}.
+
+@item kill [-@var{signal}] [@var{pid} | @var{process}]
+@cmindex kill
+Kill processes.  Takes a PID or a process object and an optional
+@var{signal} specifier which can either be a number or a signal name.
+
 @item source @var{file} [@var{argument}]@dots{}
 @cmindex source
 Source an Eshell script named @var{file} in a subshell environment,
@@ -1165,20 +1097,6 @@ Built-ins
 @cmindex time
 Show the time elapsed during the execution of @var{command}.
 
-@item umask [-S]
-@itemx umask @var{mode}
-@cmindex umask
-View the default file permissions for newly created files and
-directories.  If you pass @code{-S} or @code{--symbolic}, view the
-mode symbolically.  With @var{mode}, set the default permissions to
-this value.
-
-@item unset [@var{var}]@dots{}
-@cmindex unset
-Unset one or more variables.  As with @command{set}, the value of
-@var{var} can be a symbol, in which case it refers to a Lisp variable,
-or a string, referring to an environment variable.
-
 @item wait [@var{process}]@dots{}
 @cmindex wait
 Wait until each specified @var{process} has exited.
@@ -1188,6 +1106,130 @@ Built-ins
 For each @var{command}, identify what kind of command it is and its
 location.
 
+@end table
+
+@node Miscellaneous Commands
+@subsection Miscellaneous Commands
+@table @code
+
+@item basename @var{filename}
+@cmindex basename
+Return @var{filename} without its directory.
+
+@item clear [@var{scrollback}]
+@cmindex clear
+Scrolls the contents of the Eshell window out of sight, leaving a
+blank window.  If @var{scrollback} is non-@code{nil}, the scrollback
+contents are cleared instead, as with @command{clear-scrollback}.
+
+@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 date [@var{specified-time} [@var{zone}]]
+@cmindex date
+Print the current local time as a human-readable string.  This command
+is an alias to the Emacs Lisp function @code{current-time-string}
+(@pxref{Time of Day,,, elisp, GNU Emacs Lisp Reference Manual}).
+
+@item dirname @var{filename}
+@cmindex dirname
+Return the directory component of @var{filename}.
+
+@item echo [-n | -N] [@var{arg}]@dots{}
+@cmindex echo
+Prints the value of each @var{arg}.  By default, this prints in a
+Lisp-friendly fashion (so that the value is useful to a Lisp command
+using the result of @command{echo} as an argument).  If a single
+argument is passed, @command{echo} prints that; if multiple arguments
+are passed, it prints a list of all the arguments; otherwise, it
+prints the empty string.
+
+@vindex eshell-plain-echo-behavior
+If @code{eshell-plain-echo-behavior} is non-@code{nil}, @command{echo}
+will try to behave more like a plain shell's @command{echo}, printing
+each argument as a string, separated by a space.
+
+You can control whether @command{echo} outputs a trailing newline
+using @code{-n} to disable the trailing newline (the default behavior)
+or @code{-N} to enable it (the default when
+@code{eshell-plain-echo-behavior} is non-@code{nil}).
+
+@item eshell-debug [error | form | process]@dots{}
+@cmindex eshell-debug
+Toggle debugging information for Eshell itself.  You can pass this
+command one or more of the following arguments:
+
+@itemize @bullet
+
+@item
+@code{error}, to enable/disable Eshell trapping errors when
+evaluating commands;
+
+@item
+@code{form}, to show/hide Eshell command form manipulation in the
+buffer @code{*eshell last cmd*}; or
+
+@item
+@code{process}, to show/hide external process events in the buffer
+@code{*eshell last cmd*}.
+
+@end itemize
+
+@item exit
+@cmindex exit
+@vindex eshell-kill-on-exit
+Exit Eshell and save the history.  By default, this command kills the
+Eshell buffer, but if @code{eshell-kill-on-exit} is @code{nil}, then
+the buffer is merely buried instead.
+
+@item history [@var{n}]
+@itemx history [-arw] [@var{filename}]
+@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.
+Alternately, you can specify the following options:
+
+@table @asis
+
+@item @code{-a}, @code{--append}
+Append new history items to the history file.
+
+@item @code{-r}, @code{--read}
+Read history items from the history file and append them to the
+current shell's history.
+
+@item @code{-w}, @code{--write}
+Write the current history list to the history file.
+
+@end table
+
+@item listify [@var{arg}]@dots{}
+@cmindex listify
+Return the arguments as a single list.  With a single argument, return
+it as-is if it's already a list, or otherwise wrap it in a list.  With
+multiple arguments, return a list of all of them.
+
+@item make [@var{arg}]@dots{}
+@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 printnl [@var{arg}]@dots{}
+@cmindex printnl
+Print all the @var{arg}s separated by newlines.
+
+@item umask [-S]
+@itemx umask @var{mode}
+@cmindex umask
+View the default file permissions for newly created files and
+directories.  If you pass @code{-S} or @code{--symbolic}, view the
+mode symbolically.  With @var{mode}, set the default permissions to
+this value.
+
 @item whoami
 @cmindex whoami
 Print the current user.  This Eshell version of @command{whoami} is
@@ -1195,7 +1237,8 @@ Built-ins
 associated with that connection.
 @end table
 
-@subsection Defining new built-in commands
+@node Defining New Built-in Commands
+@subsection Defining New Built-in Commands
 While Eshell can run Lisp functions directly as commands, it may be
 more convenient to provide a special built-in command for
 Eshell.  Built-in commands are just ordinary Lisp functions designed
-- 
2.25.1


^ permalink raw reply related	[flat|nested] 11+ messages in thread
end of thread, other threads:[~2024-02-10  1:44 UTC | newest]

Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-02-07  0:02 bug#68963: 30.0.50; [PATCH] Split Eshell built-in command documentation into subsections Jim Porter
2024-02-07  3:31 ` Eli Zaretskii
2024-02-07  4:26   ` Jim Porter
2024-02-07 12:54     ` Eli Zaretskii
2024-02-07 20:22       ` Stefan Kangas
2024-02-08  2:05         ` Jim Porter
2024-02-08  7:07           ` Eli Zaretskii
2024-02-08 20:30             ` Jim Porter
2024-02-09  7:05               ` Eli Zaretskii
2024-02-10  1:44                 ` Jim Porter
2024-02-08 21:32           ` Stefan Kangas

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.