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