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.