1.1 Configuring With-Editor

With-Editor tries very hard to locate a suitable emacsclient 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 $PATH, and we have to add another kludge to find it anyway.

User Option: with-editor-emacsclient-executable ¶

The emacsclient executable used as the editor by child processes 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 exec-path, and other places where the executable could be installed, to find the emacsclient executable most suitable for the current Emacs instance.

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 your 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 systems 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 your setup.

Function: with-editor-locate-emacsclient ¶

The function used to set the initial value of the option with-editor-emacsclient-executable. There’s a lot of voodoo here.

The 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.

User Option: with-editor-sleeping-editor ¶

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 processes started inside the macro with-editor, when the process runs on a remote machine or for local processes when with-editor-emacsclient-executable is nil.

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 sh with bash (and install that), or you can use the older, less performant implementation:

"sh -c '\
echo \"WITH-EDITOR: $$ OPEN $0$1 IN $(pwd)\"; \
trap \"exit 0\" USR1; \
trap \"exit 1\" USR2; \
while true; do sleep 1; done'"

Note that the unit separator character () right after the file name ($0) is required.

Also note that using this alternative implementation leads to a delay of up to a second. The delay can be shortened by replacing sleep 1 with sleep 0.01, or if your implementation does not support floats, then by using nanosleep instead.

1.2 Using With-Editor commands

This section describes how to use the with-editor library outside of Magit. You don’t need to know any of this just to create commits using Magit.

The commands with-editor-async-shell-command and with-editor-shell-command are intended as drop in replacements for async-shell-command and shell-command. They automatically export $EDITOR making sure the executed command uses the current Emacs instance as "the editor". With a prefix argument these commands prompt for an alternative environment variable such as $GIT_EDITOR.

Command: with-editor-async-shell-command ¶

This command is like async-shell-command, but it runs the shell command with the current Emacs instance exported as $EDITOR.

Command: with-editor-shell-command ¶

This command is like shell-command, but if the shell command ends with & and is therefore run asynchronously, then the current Emacs instance is exported as $EDITOR.

To always use these variants add this to your init file:

(keymap-global-set "<remap> <async-shell-command>"
                   #'with-editor-async-shell-command)
(keymap-global-set "<remap> <shell-command>"
                   #'with-editor-shell-command)

Alternatively use the global shell-command-with-editor-mode.

Variable: shell-command-with-editor-mode ¶

When this mode is active, then $EDITOR is exported whenever ultimately shell-command is called to asynchronously run some shell command. This affects most variants of that command, whether they are defined in Emacs or in some third-party package.

The command with-editor-export-editor exports $EDITOR or another such environment variable in shell-mode, eshell-mode, term-mode and vterm-mode buffers. Use this Emacs command before executing a shell command which needs the editor set, or always arrange for the current Emacs instance to be used as editor by adding it to the appropriate mode hooks:

(add-hook 'shell-mode-hook  'with-editor-export-editor)
(add-hook 'eshell-mode-hook 'with-editor-export-editor)
(add-hook 'term-exec-hook   'with-editor-export-editor)
(add-hook 'vterm-mode-hook  'with-editor-export-editor)

Some variants of this function exist; these two forms are equivalent:

(add-hook 'shell-mode-hook
          (apply-partially 'with-editor-export-editor "GIT_EDITOR"))
(add-hook 'shell-mode-hook 'with-editor-export-git-editor)

Command: with-editor-export-editor ¶

When invoked in a shell-mode, eshell-mode, term-mode or vterm-mode buffer, this command teaches shell commands to use the current Emacs instance as the editor, by exporting $EDITOR.

Command: with-editor-export-git-editor ¶

This command is like with-editor-export-editor but exports $GIT_EDITOR.

Command: with-editor-export-hg-editor ¶

This command is like with-editor-export-editor but exports $HG_EDITOR.