| commit | author | age | ||
| 5cb5f7 | 1 | This is with-editor.info, produced by makeinfo version 6.5 from |
| C | 2 | with-editor.texi. |
| 3 | ||
| 4 | Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li> | |
| 5 | ||
| 6 | You can redistribute this document and/or modify it under the terms | |
| 7 | of the GNU General Public License as published by the Free Software | |
| 8 | Foundation, either version 3 of the License, or (at your option) | |
| 9 | any later version. | |
| 10 | ||
| 11 | This document is distributed in the hope that it will be useful, | |
| 12 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
| 14 | General Public License for more details. | |
| 15 | ||
| 16 | INFO-DIR-SECTION Emacs | |
| 17 | START-INFO-DIR-ENTRY | |
| 18 | * With-Editor: (with-editor). Using the Emacsclient as $EDITOR. | |
| 19 | END-INFO-DIR-ENTRY | |
| 20 | ||
| 21 | ||
| 22 | File: with-editor.info, Node: Top, Next: Using the With-Editor package, Up: (dir) | |
| 23 | ||
| 24 | With-Editor User Manual | |
| 25 | *********************** | |
| 26 | ||
| 27 | The library ‘with-editor’ makes it easy to use the Emacsclient as the | |
| 28 | ‘$EDITOR’ of child processes, making sure they know how to call home. | |
| 29 | For remote processes a substitute is provided, which communicates with | |
| 30 | Emacs on standard output instead of using a socket as the Emacsclient | |
| 31 | does. | |
| 32 | ||
| 33 | This library was written because Magit has to be able to do the above | |
| 34 | to allow the user to edit commit messages gracefully and to edit rebase | |
| 35 | sequences, which wouldn’t be possible at all otherwise. | |
| 36 | ||
| 37 | Because other packages can benefit from such functionality, this | |
| 38 | library is made available as a separate package. It also defines some | |
| 39 | additional functionality which makes it useful even for end-users, who | |
| 40 | don’t use Magit or another package which uses it internally. | |
| 41 | ||
| 42 | This manual is for With-Editor version 2.8.0 (v2.8.0-2-g87c96b3+1). | |
| 43 | ||
| 44 | Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li> | |
| 45 | ||
| 46 | You can redistribute this document and/or modify it under the terms | |
| 47 | of the GNU General Public License as published by the Free Software | |
| 48 | Foundation, either version 3 of the License, or (at your option) | |
| 49 | any later version. | |
| 50 | ||
| 51 | This document is distributed in the hope that it will be useful, | |
| 52 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 53 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
| 54 | General Public License for more details. | |
| 55 | ||
| 56 | * Menu: | |
| 57 | ||
| 58 | * Using the With-Editor package:: | |
| 59 | * Using With-Editor as a library:: | |
| 60 | * Debugging:: | |
| 61 | ||
| 62 | — The Detailed Node Listing — | |
| 63 | ||
| 64 | Using the With-Editor package | |
| 65 | ||
| 66 | * Configuring With-Editor:: | |
| 67 | * Using With-Editor commands:: | |
| 68 | ||
| 69 | ||
| 70 | ||
| 71 | File: with-editor.info, Node: Using the With-Editor package, Next: Using With-Editor as a library, Prev: Top, Up: Top | |
| 72 | ||
| 73 | 1 Using the With-Editor package | |
| 74 | ******************************* | |
| 75 | ||
| 76 | The ‘With-Editor’ package is used internally by Magit when editing | |
| 77 | commit messages and rebase sequences. It also provides some commands | |
| 78 | and features which are useful by themselves, even if you don’t use | |
| 79 | Magit. | |
| 80 | ||
| 81 | For information about using this library in you own package, see | |
| 82 | *note Using With-Editor as a library::. | |
| 83 | ||
| 84 | * Menu: | |
| 85 | ||
| 86 | * Configuring With-Editor:: | |
| 87 | * Using With-Editor commands:: | |
| 88 | ||
| 89 | ||
| 90 | File: with-editor.info, Node: Configuring With-Editor, Next: Using With-Editor commands, Up: Using the With-Editor package | |
| 91 | ||
| 92 | 1.1 Configuring With-Editor | |
| 93 | =========================== | |
| 94 | ||
| 95 | With-Editor tries very hard to locate a suitable ‘emacsclient’ | |
| 96 | executable, so ideally you should never have to customize the option | |
| 97 | ‘with-editor-emacsclient-executable’. When it fails to do so, then the | |
| 98 | most likely reason is that someone found yet another way to package | |
| 99 | Emacs (most likely on macOS) without putting the executable on ‘$PATH’, | |
| 100 | and we have to add another kludge to find it anyway. | |
| 101 | ||
| 102 | -- User Option: with-editor-emacsclient-executable | |
| 103 | ||
| 104 | The ‘emacsclient’ executable used as the editor by child process of | |
| 105 | this Emacs instance. By using this executable, child processes can | |
| 106 | call home to their parent process. | |
| 107 | ||
| 108 | This option is automatically set at startup by looking in | |
| 109 | ‘exec-path’, and other places where the executable could be | |
| 110 | installed, to find the ‘emacsclient’ executable most suitable for | |
| 111 | the current Emacs instance. | |
| 112 | ||
| 113 | You should *not* customize this option permanently. If you have to | |
| 114 | do it, then you should consider that a temporary kludge and inform | |
| 115 | the Magit maintainer as described in *note Debugging::. | |
| 116 | ||
| 117 | If With-Editor fails to find a suitable ‘emacsclient’ on you | |
| 118 | system, then this should be fixed for all users at once, by | |
| 119 | teaching ‘with-editor-locate-emacsclient’ how to do so on your | |
| 120 | system and system like yours. Doing it this way has the advantage, | |
| 121 | that you won’t have do it again every time you update Emacs, and | |
| 122 | that other users who have installed Emacs the same way as you have, | |
| 123 | won’t have to go through the same trouble. | |
| 124 | ||
| 125 | Note that there also is a nuclear option; setting this variable to | |
| 126 | ‘nil’ causes the "sleeping editor" described below to be used even | |
| 127 | for local child processes. Obviously we don’t recommend that you | |
| 128 | use this except in "emergencies", i.e. before we had a change to | |
| 129 | add a kludge appropriate for you setup. | |
| 130 | ||
| 131 | -- Function: with-editor-locate-emacsclient | |
| 132 | ||
| 133 | The function used to set the initial value of the option | |
| 134 | ‘with-editor-emacsclient-executable’. There’s a lot of voodoo | |
| 135 | here. | |
| 136 | ||
| 137 | The ‘emacsclient’ cannot be used when using Tramp to run a process on | |
| 138 | a remote machine. (Theoretically it could, but that would be hard to | |
| 139 | setup, very fragile, and rather insecure). | |
| 140 | ||
| 141 | With-Editor provides an alternative "editor" which can be used by | |
| 142 | remote processes in much the same way as local processes use an | |
| 143 | ‘emacsclient’ executable. This alternative is known as the "sleeping | |
| 144 | editor" because it is implemented as a shell script which sleeps until | |
| 145 | it receives a signal. | |
| 146 | ||
| 147 | -- User Option: with-editor-sleeping-editor | |
| 148 | ||
| 149 | The sleeping editor is a shell script used as the editor of child | |
| 150 | processes when the ‘emacsclient’ executable cannot be used. | |
| 151 | ||
| 152 | This fallback is used for asynchronous process started inside the | |
| 153 | macro ‘with-editor’, when the process runs on a remote machine or | |
| 154 | for local processes when ‘with-editor-emacsclient-executable’ is | |
| 155 | ‘nil’. | |
| 156 | ||
| 157 | Where the latter uses a socket to communicate with Emacs’ server, | |
| 158 | this substitute prints edit requests to its standard output on | |
| 159 | which a process filter listens for such requests. As such it is | |
| 160 | not a complete substitute for a proper ‘emacsclient’, it can only | |
| 161 | be used as ‘$EDITOR’ of child process of the current Emacs | |
| 162 | instance. | |
| 163 | ||
| 164 | Some shells do not execute traps immediately when waiting for a | |
| 165 | child process, but by default we do use such a blocking child | |
| 166 | process. | |
| 167 | ||
| 168 | If you use such a shell (e.g. ‘csh’ on FreeBSD, but not Debian), | |
| 169 | then you have to edit this option. You can either replace ‘sh’ | |
| 170 | with ‘bash’ (and install that), or you can use the older, less | |
| 171 | performant implementation: | |
| 172 | ||
| 173 | "sh -c '\ | |
| 174 | echo \"WITH-EDITOR: $$ OPEN $0 IN $(pwd)\"; \ | |
| 175 | trap \"exit 0\" USR1; \ | |
| 176 | trap \"exit 1\" USR2; \ | |
| 177 | while true; do sleep 1; done'" | |
| 178 | ||
| 179 | Note that the unit seperator character ( ) right after the file name | |
| 180 | ($0) is required. | |
| 181 | ||
| 182 | Also note that using this alternative implementation leads to a | |
| 183 | delay of up to a second. The delay can be shortened by replacing | |
| 184 | ‘sleep 1’ with ‘sleep 0.01’, or if your implementation does not | |
| 185 | support floats, then by using ‘nanosleep’ instead. | |
| 186 | ||
| 187 | ||
| 188 | File: with-editor.info, Node: Using With-Editor commands, Prev: Configuring With-Editor, Up: Using the With-Editor package | |
| 189 | ||
| 190 | 1.2 Using With-Editor commands | |
| 191 | ============================== | |
| 192 | ||
| 193 | This section describes how to use the ‘with-editor’ library _outside_ of | |
| 194 | Magit. You don’t need to know any of this just to create commits using | |
| 195 | Magit. | |
| 196 | ||
| 197 | The commands ‘with-editor-async-shell-command’ and | |
| 198 | ‘with-editor-shell-command’ are intended as drop in replacements for | |
| 199 | ‘async-shell-command’ and ‘shell-command’. They automatically export | |
| 200 | ‘$EDITOR’ making sure the executed command uses the current Emacs | |
| 201 | instance as "the editor". With a prefix argument these commands prompt | |
| 202 | for an alternative environment variable such as ‘$GIT_EDITOR’. | |
| 203 | ||
| 204 | -- Command: with-editor-async-shell-command | |
| 205 | ||
| 206 | This command is like ‘async-shell-command’, but it runs the shell | |
| 207 | command with the current Emacs instance exported as ‘$EDITOR’. | |
| 208 | ||
| 209 | -- Command: with-editor-shell-command | |
| 210 | ||
| 211 | This command is like ‘shell-command’, but if the shell command ends | |
| 212 | with ‘&’ and is therefore run asynchronously, then the current | |
| 213 | Emacs instance is exported as ‘$EDITOR’. | |
| 214 | ||
| 215 | To always use these variants add this to you init file: | |
| 216 | ||
| 217 | (define-key (current-global-map) | |
| 218 | [remap async-shell-command] 'with-editor-async-shell-command) | |
| 219 | (define-key (current-global-map) | |
| 220 | [remap shell-command] 'with-editor-shell-command) | |
| 221 | ||
| 222 | Alternatively use the global ‘shell-command-with-editor-mode’. | |
| 223 | ||
| 224 | -- Variable: shell-command-with-editor-mode | |
| 225 | ||
| 226 | When this mode is active, then ‘$EDITOR’ is exported whenever | |
| 227 | ultimately ‘shell-command’ is called to asynchronously run some | |
| 228 | shell command. This affects most variants of that command, whether | |
| 229 | they are defined in Emacs or in some third-party package. | |
| 230 | ||
| 231 | The command ‘with-editor-export-editor’ exports ‘$EDITOR’ or another | |
| 232 | such environment variable in ‘shell-mode’, ‘term-mode’ and ‘eshell-mode’ | |
| 233 | buffers. Use this Emacs command before executing a shell command which | |
| 234 | needs the editor set, or always arrange for the current Emacs instance | |
| 235 | to be used as editor by adding it to the appropriate mode hooks: | |
| 236 | ||
| 237 | (add-hook 'shell-mode-hook 'with-editor-export-editor) | |
| 238 | (add-hook 'term-exec-hook 'with-editor-export-editor) | |
| 239 | (add-hook 'eshell-mode-hook 'with-editor-export-editor) | |
| 240 | ||
| 241 | Some variants of this function exist; these two forms are equivalent: | |
| 242 | ||
| 243 | (add-hook 'shell-mode-hook | |
| 244 | (apply-partially 'with-editor-export-editor "GIT_EDITOR")) | |
| 245 | (add-hook 'shell-mode-hook 'with-editor-export-git-editor) | |
| 246 | ||
| 247 | -- Command: with-editor-export-editor | |
| 248 | ||
| 249 | When invoked in a ‘shell-mode’, ‘term-mode’, or ‘eshell-mode’ | |
| 250 | buffer, this command teaches shell commands to use the current | |
| 251 | Emacs instance as the editor, by exporting ‘$EDITOR’. | |
| 252 | ||
| 253 | -- Command: with-editor-export-git-editor | |
| 254 | ||
| 255 | This command is like ‘with-editor-export-editor’ but exports | |
| 256 | ‘$GIT_EDITOR’. | |
| 257 | ||
| 258 | -- Command: with-editor-export-hg-editor | |
| 259 | ||
| 260 | This command is like ‘with-editor-export-editor’ but exports | |
| 261 | ‘$HG_EDITOR’. | |
| 262 | ||
| 263 | ||
| 264 | File: with-editor.info, Node: Using With-Editor as a library, Next: Debugging, Prev: Using the With-Editor package, Up: Top | |
| 265 | ||
| 266 | 2 Using With-Editor as a library | |
| 267 | ******************************** | |
| 268 | ||
| 269 | This section describes how to use the ‘with-editor’ library _outside_ of | |
| 270 | Magit to teach another package how to have its child processes call | |
| 271 | home, just like Magit does. You don’t need to know any of this just to | |
| 272 | create commits using Magit. You can also ignore this if you use | |
| 273 | ‘with-editor’ outside of Magit, but only as an end-user. | |
| 274 | ||
| 275 | For information about interactive use and options that affect both | |
| 276 | interactive and non-interactive use, see *note Using the With-Editor | |
| 277 | package::. | |
| 278 | ||
| 279 | -- Macro: with-editor &rest body | |
| 280 | ||
| 281 | This macro arranges for the ‘emacsclient’ or the sleeping editor to | |
| 282 | be used as the editor of child processes, effectively teaching them | |
| 283 | to call home to the current Emacs instance when they require that | |
| 284 | the user edits a file. | |
| 285 | ||
| 286 | This is done by establishing a local binding for | |
| 287 | ‘process-environment’ and changing the value of the ‘EDITOR’ | |
| 288 | environment variable in that scope. This affects all | |
| 289 | (asynchronous) processes started by forms (dynamically) inside | |
| 290 | BODY. | |
| 291 | ||
| 292 | If BODY begins with a literal string, then that variable is set | |
| 293 | instead of ‘EDITOR’. | |
| 294 | ||
| 295 | -- Macro: with-editor envvar &rest body | |
| 296 | ||
| 297 | This macro is like ‘with-editor’ instead that the ENVVAR argument | |
| 298 | is required and that it is evaluated at run-time. | |
| 299 | ||
| 300 | -- Function: with-editor-set-process-filter process filter | |
| 301 | ||
| 302 | This function is like ‘set-process-filter’ but ensures that adding | |
| 303 | the new FILTER does not remove the ‘with-editor-process-filter’. | |
| 304 | This is done by wrapping the two filter functions using a lambda, | |
| 305 | which becomes the actual filter. It calls | |
| 306 | ‘with-editor-process-filter’ first, passing ‘t’ as | |
| 307 | NO-STANDARD-FILTER. Then it calls FILTER. | |
| 308 | ||
| 309 | ||
| 310 | File: with-editor.info, Node: Debugging, Prev: Using With-Editor as a library, Up: Top | |
| 311 | ||
| 312 | 3 Debugging | |
| 313 | *********** | |
| 314 | ||
| 315 | With-Editor tries very hard to locate a suitable ‘emacsclient’ | |
| 316 | executable, and then sets option ‘with-editor-emacsclient-executable’ | |
| 317 | accordingly. In very rare cases this fails. When it does fail, then | |
| 318 | the most likely reason is that someone found yet another way to package | |
| 319 | Emacs (most likely on macOS) without putting the executable on ‘$PATH’, | |
| 320 | and we have to add another kludge to find it anyway. | |
| 321 | ||
| 322 | If you are having problems using ‘with-editor’, e.g. you cannot | |
| 323 | commit in Magit, then please open a new issue at | |
| 324 | <https://github.com/magit/with-editor/issues> and provide information | |
| 325 | about your Emacs installation. Most importantly how did you install | |
| 326 | Emacs and what is the output of ‘M-x with-editor-debug RET’. | |
| 327 | ||
| 328 | ||
| 329 | ||
| 330 | Tag Table: | |
| 331 | Node: Top773 | |
| 332 | Node: Using the With-Editor package2535 | |
| 333 | Node: Configuring With-Editor3121 | |
| 334 | Node: Using With-Editor commands7670 | |
| 335 | Node: Using With-Editor as a library10865 | |
| 336 | Node: Debugging12828 | |
| 337 | ||
| 338 | End Tag Table | |
| 339 | ||
| 340 | ||
| 341 | Local Variables: | |
| 342 | coding: utf-8 | |
| 343 | End: | |
