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