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