With-Editor tries very hard to locate a suitable
executable, so ideally you should never have to customize the option
with-editor-emacsclient-executable. When it fails to do so, then the
most likely reason is that someone found yet another way to package
Emacs (most likely on macOS) without putting the executable on
and we have to add another kludge to find it anyway.
emacsclient executable used as the editor by child process of
this Emacs instance. By using this executable, child processes can
call home to their parent process.
This option is automatically set at startup by looking in
and other places where the executable could be installed, to find
emacsclient executable most suitable for the current Emacs
You should not customize this option permanently. If you have to do it, then you should consider that a temporary kludge and inform the Magit maintainer as described in Debugging.
If With-Editor fails to find a suitable
emacsclient on you system,
then this should be fixed for all users at once, by teaching
with-editor-locate-emacsclient how to do so on your system and
system like yours. Doing it this way has the advantage, that you
won’t have do it again every time you update Emacs, and that other
users who have installed Emacs the same way as you have, won’t have
to go through the same trouble.
Note that there also is a nuclear option; setting this variable to
nil causes the "sleeping editor" described below to be used even for
local child processes. Obviously we don’t recommend that you use
this except in "emergencies", i.e. before we had a change to add a
kludge appropriate for you setup.
The function used to set the initial value of the option
with-editor-emacsclient-executable. There’s a lot of voodoo here.
emacsclient cannot be used when using Tramp to run a process on a
remote machine. (Theoretically it could, but that would be hard to
setup, very fragile, and rather insecure).
With-Editor provides an alternative "editor" which can be used by
remote processes in much the same way as local processes use an
emacsclient executable. This alternative is known as the "sleeping
editor" because it is implemented as a shell script which sleeps until
it receives a signal.
The sleeping editor is a shell script used as the editor of child
processes when the
emacsclient executable cannot be used.
This fallback is used for asynchronous process started inside the
with-editor, when the process runs on a remote machine or for
local processes when
Where the latter uses a socket to communicate with Emacs’ server,
this substitute prints edit requests to its standard output on
which a process filter listens for such requests. As such it is
not a complete substitute for a proper
emacsclient, it can only
be used as
$EDITOR of child process of the current Emacs instance.
Some shells do not execute traps immediately when waiting for a child process, but by default we do use such a blocking child process.
If you use such a shell (e.g.
csh on FreeBSD, but not Debian), then
you have to edit this option. You can either replace
(and install that), or you can use the older, less performant
"sh -c '\ echo \"WITH-EDITOR: $$ OPEN $0\"; \ trap \"exit 0\" USR1; \ trap \"exit 1\" USR2; \ while true; do sleep 1; done'"
This leads to a delay of up to a second. The delay can be shortened
sleep 1 with
sleep 0.01, or if your implementation does
not support floats, then by using
nanosleep 0.01 instead.