This is with-editor.info, produced by makeinfo version 5.2 from with-editor.texi. The library ‘with-editor’ makes it easy to use the Emacsclient as the ‘$EDITOR’ of child processes, making sure they know how to call home. For remote processes a substitute is provided, which communicates with Emacs on standard output instead of using a socket as the Emacsclient does. This library was written because Magit has to be able to do the above to allow the user to edit commit messages gracefully and to edit rebase sequences, which wouldn’t be possible at all otherwise. Because other packages can benefit from such functionality, this library is made available as a separate package. It also defines some additional functionality which makes it useful even for end-users, who don’t use Magit or another package which uses it internally. Copyright (C) 2015-2016 Jonas Bernoulli You can redistribute this document and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * With-Editor: (with-editor). Using the Emacsclient as $EDITOR. END-INFO-DIR-ENTRY  File: with-editor.info, Node: Top, Next: Using the With-Editor package, Up: (dir) With-Editor User Manual *********************** The library ‘with-editor’ makes it easy to use the Emacsclient as the ‘$EDITOR’ of child processes, making sure they know how to call home. For remote processes a substitute is provided, which communicates with Emacs on standard output instead of using a socket as the Emacsclient does. This library was written because Magit has to be able to do the above to allow the user to edit commit messages gracefully and to edit rebase sequences, which wouldn’t be possible at all otherwise. Because other packages can benefit from such functionality, this library is made available as a separate package. It also defines some additional functionality which makes it useful even for end-users, who don’t use Magit or another package which uses it internally. Copyright (C) 2015-2016 Jonas Bernoulli You can redistribute this document and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. * Menu: * Using the With-Editor package:: * Using With-Editor as a library:: * Debugging:: — The Detailed Node Listing — Using the With-Editor package * Configuring With-Editor:: * Using With-Editor commands::  File: with-editor.info, Node: Using the With-Editor package, Next: Using With-Editor as a library, Prev: Top, Up: Top 1 Using the With-Editor package ******************************* The ‘With-Editor’ package is used internally by Magit when editing commit messages and rebase sequences. It also provides some commands and features which are useful by themselves, even if you don’t use Magit. For information about using this library in you own package, see *note Using With-Editor as a library: Using With-Editor as a library. * Menu: * Configuring With-Editor:: * Using With-Editor commands::  File: with-editor.info, Node: Configuring With-Editor, Next: Using With-Editor commands, Up: Using the With-Editor package 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 OS X) 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 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 ‘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 *note Debugging: 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 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. -- 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 process 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. It is unlikely that you should ever have to customize this option.  File: with-editor.info, Node: Using With-Editor commands, Prev: Configuring With-Editor, Up: Using the With-Editor package 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 Like ‘async-shell-command’, but the command is run with the current Emacs instance exported as ‘$EDITOR’. -- Command: with-editor-shell-command Like ‘async-shell-command’, but the command is run with the current Emacs instance exported as ‘$EDITOR’. This only has an effect if the command is run asynchronously, i.e. when the command ends with ‘&’. To always use these variants add this to you init file: (define-key (current-global-map) [remap async-shell-command] 'with-editor-async-shell-command) (define-key (current-global-map) [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’, ‘term-mode’ and ‘eshell-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 'term-mode-hook 'with-editor-export-editor) (add-hook 'eshell-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’, ‘term-mode’, or ‘eshell-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 Like ‘with-editor-export-editor’ but exports ‘$GIT_EDITOR’. -- Command: with-editor-export-hg-editor Like ‘with-editor-export-editor’ but exports ‘$HG_EDITOR’.  File: with-editor.info, Node: Using With-Editor as a library, Next: Debugging, Prev: Using the With-Editor package, Up: Top 2 Using With-Editor as a library ******************************** This section describes how to use the with-editor library _outside_ of Magit to teach another package how to have its child processes call home, just like Magit does. You don’t need to know any of this just to create commits using Magit. You can also ignore this if you use ‘with-editor’ outside of Magit, but only as an end-user. For information about interactive use and options which affect both interactive and non-interactive use, see *note Using the With-Editor package: Using the With-Editor package. -- Macro: with-editor &rest body This macro arranges for the emacsclient or the sleeping editor to be used as the editor of child processes, effectively teaching them to call home to the current emacs instance when they require that the user edits a file. This is essentially done by establishing a local binding for ‘process-environment’ and changing the value of the ‘$EDITOR’ environment variable. This affects all processes started by forms inside BODY. -- Function: with-editor-set-process-filter process filter This function is like ‘set-process-filter’ but ensures that adding the new FILTER does not remove the ‘with-editor-process-filter’. This is done by wrapping the two filter functions using a lambda, which becomes the actual filter. It calls ‘with-editor-process-filter’ first, passing ‘t’ as NO-STANDARD-FILTER. Then it calls FILTER.  File: with-editor.info, Node: Debugging, Prev: Using With-Editor as a library, Up: Top 3 Debugging *********** With-Editor tries very hard to locate a suitable emacsclient executable, and then sets option ‘with-editor-emacsclient-executable’ accordingly. In very rare cases this fails. When it does fail, then the most likely reason is that someone found yet another way to package Emacs (most likely on OS X) without putting the executable on ‘$PATH’, and we have to add another kludge to find it anyway. If you are having problems using ‘with-editor’, e.g. you cannot commit in Magit, then please open a new issue at and provide information about your Emacs installation. Most importantly how did you install Emacs and what is the output of ‘M-x with-editor-debug’?  Tag Table: Node: Top1545 Node: Using the With-Editor package3236 Node: Configuring With-Editor3852 Node: Using With-Editor commands7459 Node: Using With-Editor as a library10622 Node: Debugging12294  End Tag Table  Local Variables: coding: utf-8 End: