New user option 'shell-history-file-name'

* doc/emacs/misc.texi (Shell Ring): Explain shell-history-file-name.

* doc/misc/tramp.texi (Inline methods): Be more specific with containers.
(Remote processes): New subsection "Managing remote shell history".
Explain shell-history-file-name.
(Frequently Asked Questions): Add items to Tramp speedup.  Remove
entry about history file.

* etc/NEWS: New user option 'shell-history-file-name'.

* lisp/shell.el (shell-history-file-name): New defcustom.
(shell-mode): Use it.  (Bug#71049)

2 files changed, 82 insertions, 58 deletions

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 3bee88bca86..68ea030e219 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -1331,16 +1331,18 @@ buffer, or even killing large parts of it, does not affect the history
 that these commands access.
 
 @vindex comint-input-ring-file-name
+@vindex shell-history-file-name
+@cindex @env{HISTFILE} environment variable
   Some shells store their command histories in files so that you can
-refer to commands from previous shell sessions.  Emacs reads
-the command history file for your chosen shell, to initialize its own
-command history.  The file name is @file{~/.bash_history} for bash,
-@file{~/.sh_history} for ksh, and @file{~/.history} for other shells.
-
-@vindex tramp-histfile-override
-  If you run the shell on a remote host, this setting might be
-overwritten by the variable @code{tramp-histfile-override}.  It is
-recommended to set this variable to @code{nil}.
+refer to commands from previous shell sessions.  Emacs reads the command
+history file for your chosen shell, to initialize its own command
+history.  The history file name is the string specified in
+@code{shell-history-file-name}.  If that user option is @code{t}, the
+command history is not read.  If the value is @code{nil}, the command
+history is read from the file specified in environment variable
+@env{HISTFILE}, or from @file{~/.bash_history} for bash,
+@file{~/.sh_history} for ksh, @file{~/.zsh_history"} for zsh, or
+@file{~/.history} for other shells.
 
 @node Shell History Copying
 @subsubsection Shell History Copying
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 74081767caa..ec8a8d5c3eb 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -976,7 +976,8 @@ session.
 @end table
 
 @noindent
-The following methods allow to access containers in different ways:
+The following methods allow to access running containers in different
+ways:
 
 @table @asis
 @item @option{docker}
@@ -1017,6 +1018,9 @@ The host name may be either a container's name or ID, as returned by
 the default Toolbox container for the host will be used.  There is no
 such default for Distrobox.
 
+Contrary to the other container-based methods, these two methods start
+a created container, if it isn't running yet.
+
 These are optional methods, @pxref{Optional methods}.  They do not
 support user names.
 
@@ -4080,8 +4084,59 @@ host.  Furthermore, set @code{tramp-use-connection-share} to
 unwanted side effects.
 
 
+@anchor{Managing remote shell history}
+@subsection Managing remote shell history
+@cindex shell history
+@vindex tramp-histfile-override
+@vindex HISTFILE@r{, environment variable}
+@vindex HISTFILESIZE@r{, environment variable}
+@vindex HISTSIZE@r{, environment variable}
+
+Due to the remote shell saving tilde expansions triggered by
+@value{tramp}, the shell history file is probably growing rapidly.
+@value{tramp} can suppress this behavior with the user option
+@code{tramp-histfile-override}.  When set to @code{t}, environment
+variable @env{HISTFILE} is unset, and environment variables
+@env{HISTFILESIZE} and @env{HISTSIZE} are set to 0.  Don't use this
+with @command{bash} 5.0.0.  There is a bug in @command{bash} which
+lets @command{bash} die.
+
+Alternatively, @code{tramp-histfile-override} could be a string.
+Environment variable @env{HISTFILE} is set to this file name then.  Be
+careful when setting to @file{/dev/null}; this might result in
+undesired results when using @command{bash} as remote shell.
+
+Another approach is to disable @value{tramp}'s handling of the
+@env{HISTFILE} at all by setting @code{tramp-histfile-override} to
+@code{nil}.  In this case, saving history could be turned off by
+putting this shell code in @file{.bashrc} or @file{.kshrc}:
+
+@example
+@group
+if [ -f $HOME/.sh_history ] ; then
+   /bin/rm $HOME/.sh_history
+fi
+if [ "$@{HISTFILE-unset@}" != "unset" ] ; then
+   unset HISTFILE
+fi
+if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then
+   unset HISTSIZE
+fi
+@end group
+@end example
+
+For @option{ssh}-based method, add the following line to your
+@file{~/.ssh/environment}:
+
+@example
+HISTFILE=/dev/null
+@end example
+
+
 @subsection Running @code{shell} on a remote host
 @cindex @code{shell}
+@vindex explicit-shell-file-name
+@vindex shell-history-file-name
 
 Set @code{explicit-shell-file-name} to the appropriate shell name
 when using @value{tramp} between two hosts with different operating
@@ -4126,6 +4181,14 @@ of @code{explicit-shell-file-name} for different remote hosts.
 @end group
 @end lisp
 
+The command @code{shell} reads the remote history file in order to to
+initialize the history input ring.  You can set the user option
+@code{shell-history-file-name} in order to specify which remote
+history file is taken, or whether to suppress this at all.  It accepts
+the same values as @code{tramp-histfile-override}, see @pxref{Managing
+remote shell history}. @code{shell-history-file-name} accepts also
+connection-local values in @code{shell} buffers.
+
 
 @subsection Running @code{shell-command} on a remote host
 @cindex @code{shell-command}
@@ -5171,6 +5234,13 @@ connections, apply the following code.
 @end lisp
 
 @item
+Use direct asynchronous processes if possible.
+
+@item
+Suppress reading the remote history file in @code{shell}.  Set
+@code{shell-history-file-name} to @code{t}.
+
+@item
 Disable excessive traces.  Set @code{tramp-verbose} to 3 or lower,
 default being 3.  Increase trace levels temporarily when hunting for
 bugs.
@@ -5477,54 +5547,6 @@ as follows:
 
 
 @item
-Why is @file{~/.sh_history} on the remote host growing?
-
-@vindex tramp-histfile-override
-@vindex HISTFILE@r{, environment variable}
-@vindex HISTFILESIZE@r{, environment variable}
-@vindex HISTSIZE@r{, environment variable}
-Due to the remote shell saving tilde expansions triggered by
-@value{tramp}, the history file is probably growing rapidly.
-@value{tramp} can suppress this behavior with the user option
-@code{tramp-histfile-override}.  When set to @code{t}, environment
-variable @env{HISTFILE} is unset, and environment variables
-@env{HISTFILESIZE} and @env{HISTSIZE} are set to 0.  Don't use this
-with @command{bash} 5.0.0.  There is a bug in @command{bash} which
-lets @command{bash} die.
-
-Alternatively, @code{tramp-histfile-override} could be a string.
-Environment variable @env{HISTFILE} is set to this file name then.  Be
-careful when setting to @file{/dev/null}; this might result in
-undesired results when using @command{bash} as remote shell.
-
-Another approach is to disable @value{tramp}'s handling of the
-@env{HISTFILE} at all by setting @code{tramp-histfile-override} to
-@code{nil}.  In this case, saving history could be turned off by
-putting this shell code in @file{.bashrc} or @file{.kshrc}:
-
-@example
-@group
-if [ -f $HOME/.sh_history ] ; then
-   /bin/rm $HOME/.sh_history
-fi
-if [ "$@{HISTFILE-unset@}" != "unset" ] ; then
-   unset HISTFILE
-fi
-if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then
-   unset HISTSIZE
-fi
-@end group
-@end example
-
-For @option{ssh}-based method, add the following line to your
-@file{~/.ssh/environment}:
-
-@example
-HISTFILE=/dev/null
-@end example
-
-
-@item
 Where are remote files trashed to?
 
 @vindex remote-file-name-inhibit-delete-by-moving-to-trash