manual: Regenerate

2 files changed, 65 insertions, 49 deletions

diff --git a/Documentation/magit.org b/Documentation/magit.org
index 712761b..e277c8a 100644
--- a/Documentation/magit.org
+++ b/Documentation/magit.org
@@ -8,7 +8,7 @@
 #+TEXINFO_DIR_CATEGORY: Emacs
 #+TEXINFO_DIR_TITLE: Magit: (magit).
 #+TEXINFO_DIR_DESC: Using Git from Emacs with Magit.
-#+SUBTITLE: for version 3.1.1 (v3.1.1-24-g96137d22+1)
+#+SUBTITLE: for version 3.1.1 (v3.1.1-53-gcbe1c0948+1)
 
 #+TEXINFO_DEFFN: t
 #+OPTIONS: H:4 num:3 toc:2
@@ -25,7 +25,7 @@ directly from within Emacs.  While many fine Git clients exist, only
 Magit and Git itself deserve to be called porcelains.
 
 #+TEXINFO: @noindent
-This manual is for Magit version 3.1.1 (v3.1.1-24-g96137d22+1).
+This manual is for Magit version 3.1.1 (v3.1.1-53-gcbe1c0948+1).
 
 #+BEGIN_QUOTE
 Copyright (C) 2015-2021 Jonas Bernoulli <jonas@bernoul.li>
diff --git a/Documentation/magit.texi b/Documentation/magit.texi
index f5693fe..f1043d7 100644
--- a/Documentation/magit.texi
+++ b/Documentation/magit.texi
@@ -31,7 +31,7 @@ General Public License for more details.
 @finalout
 @titlepage
 @title Magit User Manual
-@subtitle for version 3.1.1 (v3.1.1-24-g96137d22+1)
+@subtitle for version 3.1.1 (v3.1.1-53-gcbe1c0948+1)
 @author Jonas Bernoulli
 @page
 @vskip 0pt plus 1filll
@@ -53,7 +53,7 @@ directly from within Emacs.  While many fine Git clients exist, only
 Magit and Git itself deserve to be called porcelains.
 
 @noindent
-This manual is for Magit version 3.1.1 (v3.1.1-24-g96137d22+1).
+This manual is for Magit version 3.1.1 (v3.1.1-53-gcbe1c0948+1).
 
 @quotation
 Copyright (C) 2015-2021 Jonas Bernoulli <jonas@@bernoul.li>
@@ -2595,56 +2595,64 @@ This command runs @code{git gui} in the current repository.
 @node Git Executable
 @subsection Git Executable
 
-Except on MS Windows, Magit defaults to running Git without specifying
-the path to the git executable.  Instead the first executable found by
-Emacs on @code{exec-path} is used (whose value in turn is set based on the
-value of the environment variable @code{$PATH} when Emacs was started).
+When Magit calls Git, then it may do so using the absolute path to the
+@code{git} executable, or using just its name.
 
-This has the advantage that it continues to work even when using Tramp
-to connect to a remote machine on which the executable is found in a
-different place.  The downside is that if you have multiple versions
-of Git installed, then you might end up using another version than the
-one you think you are using.
+When running @code{git} locally and the @code{system-type} is @code{windows-nt} (any
+Windows version) or @code{darwin} (macOS) then @code{magit-git-executable} is set
+to an absolute path when Magit is loaded.
 
-@table @asis
-@kindex M-x magit-version
-@cindex magit-version
-@item @kbd{M-x magit-version} @tie{}@tie{}@tie{}@tie{}(@code{magit-version})
+On Windows it is necessary to use an absolute path because Git comes
+with several wrapper scripts for the actual @code{git} binary, which are also
+placed on @code{$PATH}, and using one of these wrappers instead of the binary
+would degrade performance horribly.  For some macOS users using just
+the name of the executable also performs horribly, so we avoid doing
+that on that platform as well.  On other platforms, using just the
+name seems to work just fine.
 
-This command shows the currently used versions of Magit, Git, and
-Emacs in the echo area.  Non-interactively this just returns the
-Magit version.
-@end table
-
-When the @code{system-type} is @code{windows-nt}, then @code{magit-git-executable} is set
-to an absolute path when Magit is first loaded.  This is necessary
-because Git on that platform comes with several wrapper scripts for
-the actual git binary, which are also placed on @code{$PATH}, and using one
-of these wrappers instead of the binary would degrade performance
-horribly.
-
-If Magit doesn't find the correct executable then you @strong{can} work
-around that by setting @code{magit-git-executable} to an absolute path.
-But note that doing so is a kludge.  It is better to make sure the
-order in the environment variable @code{$PATH} is correct, and that Emacs
-is started with that environment in effect.  The command
-@code{magit-debug-git-executable} can be useful to find out where Emacs is
-searching for git.  If you have to connect from Windows to a
-non-Windows machine, then you must change the value to "git".
+Using an absolute path when running @code{git} on a remote machine over
+Tramp, would be problematic to use an absolute path that is suitable
+on the local machine, so a separate option is used to control the name
+or path that is used on remote machines.
 
 @defopt magit-git-executable
 
-The git executable used by Magit, either the full path to the
-executable or the string "git" to let Emacs find the executable
-itself, using the standard mechanism for doing such things.
+The @code{git} executable used by Magit on the local host.  This should be
+either the absolute path to the executable, or the string "git" to
+let Emacs find the executable itself, using the standard mechanism
+for doing such things.
+@end defopt
+
+@defopt magit-remote-git-executable
+
+The @code{git} executable used by Magit on remote machines over Tramp.
+Normally this should be just the string "git".
 @end defopt
 
+If Emacs is unable find the correct executable, then you can work
+around that by explicitly setting the value of these two options.
+Doing that should be considered a kludge; it is better to make sure
+that the order in the environment variable @code{$PATH} is correct, and
+that Emacs is started with that environment in effect.
+
+The command @code{magit-debug-git-executable} can be useful to find out where
+Emacs is searching for @code{git}.
+
 @table @asis
 @kindex M-x magit-debug-git-executable
 @cindex magit-debug-git-executable
 @item @kbd{M-x magit-debug-git-executable} @tie{}@tie{}@tie{}@tie{}(@code{magit-debug-git-executable})
 
-Display a buffer with information about @code{magit-git-executable}.
+This command displays a buffer with information about
+@code{magit-git-executable} and  @code{magit-remote-git-executable}.
+
+@kindex M-x magit-version
+@cindex magit-version
+@item @kbd{M-x magit-version} @tie{}@tie{}@tie{}@tie{}(@code{magit-version})
+
+This command shows the currently used versions of Magit, Git, and
+Emacs in the echo area.  Non-interactively this just returns the
+Magit version.
 @end table
 
 @node Global Git Arguments
@@ -10343,14 +10351,6 @@ faster @code{vfork} will be used.  (The creation of child processes still
 takes about twice as long on Darwin compared to Linux.)  See @footnote{@uref{https://lists.gnu.org/archive/html/bug-gnu-emacs/2017-04/msg00201.html}}
 for more information.
 
-On Catalina, and potentially other macOS releases, there may be a
-performance problem where any action takes 20 times longer on Darwin
-than on Linux.  This can be worked around by setting
-@code{magit-git-executable} to the absolute path of the @code{git} executable,
-instead of relying on resolving the @code{$PATH}.  You should not do that if
-you want to use Magit on remote machines using Tramp and if @code{git} is not
-installed in the same location on those machines.
-
 @node Default Bindings
 @subsection Default Bindings
 
@@ -10520,6 +10520,22 @@ add a section containing git's standard error in the current
 repository's process buffer.
 @end defun
 
+@defun magit-process-git destination &rest args
+
+Calls Git synchronously in a separate process, returning its exit
+code.  DESTINATION specifies how to handle the output, like for
+@code{call-process}, except that file handlers are supported.  Enables
+Cygwin's "noglob" option during the call and ensures unix eol
+conversion.
+@end defun
+
+@defun magit-process-file process &optional infile buffer display &rest args
+
+Processes files synchronously in a separate process.  Identical to
+@code{process-file} but temporarily enables Cygwin's "noglob" option during
+the call and ensures unix eol conversion.
+@end defun
+
 If an error occurs when using one of the above functions, then that
 is usually due to a bug, i.e. using an argument which is not
 actually supported.  Such errors are usually not reported, but when