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