README.md
1With-Editor
2===========
3
4This library makes it possible to reliably use the Emacsclient as
5the `$EDITOR` of child processes. It makes sure that they know how
6to call home. For remote processes a substitute is provided, which
7communicates with Emacs on standard output/input instead of using a
8socket as the Emacsclient does.
9
10It provides the commands `with-editor-async-shell-command` and
11`with-editor-shell-command`, which are intended as replacements
12for `async-shell-command` and `shell-command`. They automatically
13export `$EDITOR` making sure the executed command uses the current
14Emacs instance as "the editor". With a prefix argument these
15commands prompt for an alternative environment variable such as
16`$GIT_EDITOR`. To always use these variants add this to your init
17file:
18
19 (define-key (current-global-map)
20 [remap async-shell-command] 'with-editor-async-shell-command)
21 (define-key (current-global-map)
22 [remap shell-command] 'with-editor-shell-command)
23
24Alternatively use the global `shell-command-with-editor-mode`,
25which always sets `$EDITOR` for all Emacs commands which ultimately
26use `shell-command` to asynchronously run some shell command.
27
28The command `with-editor-export-editor` exports `$EDITOR` or
29another such environment variable in `shell-mode`, `eshell-mode`,
30`term-mode` and `vterm-mode` buffers. Use this Emacs command
31before executing a shell command which needs the editor set, or
32always arrange for the current Emacs instance to be used as editor
33by adding it to the appropriate mode hooks:
34
35 (add-hook 'shell-mode-hook 'with-editor-export-editor)
36 (add-hook 'eshell-mode-hook 'with-editor-export-editor)
37 (add-hook 'term-exec-hook 'with-editor-export-editor)
38 (add-hook 'vterm-mode-hook 'with-editor-export-editor)
39
40Some variants of this function exist, these two forms are
41equivalent:
42
43 (add-hook 'shell-mode-hook
44 (apply-partially 'with-editor-export-editor "GIT_EDITOR"))
45 (add-hook 'shell-mode-hook 'with-editor-export-git-editor)
46
47This library can also be used by other packages which need to use
48the current Emacs instance as editor. In fact this library was
49written for Magit and its `git-commit-mode` and `git-rebase-mode`.
50Consult `git-rebase.el` and the related code in `magit-sequence.el`
51for a simple example.
52