path: root/with-editor.org

#+TITLE: With-Editor User Manual
#+AUTHOR: Jonas Bernoulli
#+EMAIL: jonas@bernoul.li
#+DATE: 2015-2018
#+LANGUAGE: en

#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: With-Editor: (with-editor).
#+TEXINFO_DIR_DESC: Using the Emacsclient as $EDITOR
#+SUBTITLE: for version 2.7.1
#+BIND: ox-texinfo+-before-export-hook ox-texinfo+-update-version-strings

#+TEXINFO_DEFFN: t
#+OPTIONS: H:4 num:4 toc:2

The library ~with-editor~ makes it easy to use the Emacsclient as the
~$EDITOR~ of child processes, making sure they know how to call home.
For remote processes a substitute is provided, which communicates with
Emacs on standard output instead of using a socket as the Emacsclient
does.

This library was written because Magit has to be able to do the above
to allow the user to edit commit messages gracefully and to edit
rebase sequences, which wouldn't be possible at all otherwise.

Because other packages can benefit from such functionality, this
library is made available as a separate package.  It also defines some
additional functionality which makes it useful even for end-users, who
don't use Magit or another package which uses it internally.

#+TEXINFO: @noindent
This manual is for With-Editor version 2.7.1.

#+BEGIN_QUOTE
Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li>

You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any
later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
#+END_QUOTE

* Using the With-Editor package

The ~With-Editor~ package is used internally by Magit when editing
commit messages and rebase sequences.  It also provides some commands
and features which are useful by themselves, even if you don't use
Magit.

For information about using this library in you own package, see
[[*Using With-Editor as a library]].

** Configuring With-Editor

With-Editor tries very hard to locate a suitable ~emacsclient~
executable, so ideally you should never have to customize the option
~with-editor-emacsclient-executable~.  When it fails to do so, then the
most likely reason is that someone found yet another way to package
Emacs (most likely on macOS) without putting the executable on ~$PATH~,
and we have to add another kludge to find it anyway.

- User Option: with-editor-emacsclient-executable

  The ~emacsclient~ executable used as the editor by child process of
  this Emacs instance.  By using this executable, child processes can
  call home to their parent process.

  This option is automatically set at startup by looking in ~exec-path~,
  and other places where the executable could be installed, to find
  the ~emacsclient~ executable most suitable for the current Emacs
  instance.

  You should *not* customize this option permanently.  If you have to do
  it, then you should consider that a temporary kludge and inform the
  Magit maintainer as described in [[*Debugging][Debugging]].

  If With-Editor fails to find a suitable ~emacsclient~ on you system,
  then this should be fixed for all users at once, by teaching
  ~with-editor-locate-emacsclient~ how to do so on your system and
  system like yours. Doing it this way has the advantage, that you
  won't have do it again every time you update Emacs, and that other
  users who have installed Emacs the same way as you have, won't have
  to go through the same trouble.

  Note that there also is a nuclear option; setting this variable to
  ~nil~ causes the "sleeping editor" described below to be used even for
  local child processes.  Obviously we don't recommend that you use
  this except in "emergencies", i.e. before we had a change to add a
  kludge appropriate for you setup.

- Function: with-editor-locate-emacsclient

  The function used to set the initial value of the option
  ~with-editor-emacsclient-executable~.  There's a lot of voodoo here.

The ~emacsclient~ cannot be used when using Tramp to run a process on a
remote machine.  (Theoretically it could, but that would be hard to
setup, very fragile, and rather insecure).

With-Editor provides an alternative "editor" which can be used by
remote processes in much the same way as local processes use an
~emacsclient~ executable.  This alternative is known as the "sleeping
editor" because it is implemented as a shell script which sleeps until
it receives a signal.

- User Option: with-editor-sleeping-editor

  The sleeping editor is a shell script used as the editor of child
  processes when the ~emacsclient~ executable cannot be used.

  This fallback is used for asynchronous process started inside the
  macro ~with-editor~, when the process runs on a remote machine or for
  local processes when ~with-editor-emacsclient-executable~ is ~nil~.

  Where the latter uses a socket to communicate with Emacs' server,
  this substitute prints edit requests to its standard output on
  which a process filter listens for such requests.  As such it is
  not a complete substitute for a proper ~emacsclient~, it can only
  be used as ~$EDITOR~ of child process of the current Emacs instance.

  Some shells do not execute traps immediately when waiting for a
  child process, but by default we do use such a blocking child
  process.

  If you use such a shell (e.g. ~csh~ on FreeBSD, but not Debian), then
  you have to edit this option.  You can either replace ~sh~ with ~bash~
  (and install that), or you can use the older, less performant
  implementation:

  #+BEGIN_SRC emacs-lisp
    "sh -c '\
    echo \"WITH-EDITOR: $$ OPEN $0\"; \
    trap \"exit 0\" USR1; \
    trap \"exit 1\" USR2; \
    while true; do sleep 1; done'"
  #+END_SRC

  This leads to a delay of up to a second.  The delay can be shortened
  by replacing ~sleep 1~ with ~sleep 0.01~, or if your implementation does
  not support floats, then by using ~nanosleep 0.01~ instead.

** Using With-Editor commands

This section describes how to use the ~with-editor~ library /outside/ of
Magit.  You don't need to know any of this just to create commits
using Magit.

The commands ~with-editor-async-shell-command~ and
~with-editor-shell-command~ are intended as drop in replacements for
~async-shell-command~ and ~shell-command~.  They automatically export
~$EDITOR~ making sure the executed command uses the current Emacs
instance as "the editor".  With a prefix argument these commands
prompt for an alternative environment variable such as ~$GIT_EDITOR~.

- Command: with-editor-async-shell-command

  This command is like ~async-shell-command~, but it runs the shell
  command with the current Emacs instance exported as ~$EDITOR~.

- Command: with-editor-shell-command

  This command is like ~async-shell-command~, but it runs the shell
  command with the current Emacs instance exported as ~$EDITOR~.  This
  only has an effect if the shell command is run asynchronously,
  i.e. when the command ends with ~&~.

To always use these variants add this to you init file:

#+BEGIN_SRC emacs-lisp
  (define-key (current-global-map)
    [remap async-shell-command] 'with-editor-async-shell-command)
  (define-key (current-global-map)
    [remap shell-command] 'with-editor-shell-command)
#+END_SRC

Alternatively use the global ~shell-command-with-editor-mode~.

- Variable: shell-command-with-editor-mode

  When this mode is active, then ~$EDITOR~ is exported whenever
  ultimately ~shell-command~ is called to asynchronously run some shell
  command.  This affects most variants of that command, whether they
  are defined in Emacs or in some third-party package.

The command ~with-editor-export-editor~ exports ~$EDITOR~ or
another such environment variable in ~shell-mode~, ~term-mode~ and
~eshell-mode~ buffers.  Use this Emacs command before executing a
shell command which needs the editor set, or always arrange for the
current Emacs instance to be used as editor by adding it to the
appropriate mode hooks:

#+BEGIN_SRC emacs-lisp
  (add-hook 'shell-mode-hook  'with-editor-export-editor)
  (add-hook 'term-exec-hook   'with-editor-export-editor)
  (add-hook 'eshell-mode-hook 'with-editor-export-editor)
#+END_SRC

Some variants of this function exist; these two forms are equivalent:

#+BEGIN_SRC emacs-lisp
  (add-hook 'shell-mode-hook
            (apply-partially 'with-editor-export-editor "GIT_EDITOR"))
  (add-hook 'shell-mode-hook 'with-editor-export-git-editor)
#+END_SRC

- Command: with-editor-export-editor

  When invoked in a ~shell-mode~, ~term-mode~, or ~eshell-mode~ buffer, this
  command teaches shell commands to use the current Emacs instance as
  the editor, by exporting ~$EDITOR~.

- Command: with-editor-export-git-editor

  This command is like ~with-editor-export-editor~ but exports
  ~$GIT_EDITOR~.

- Command: with-editor-export-hg-editor

  This command is like ~with-editor-export-editor~ but exports
  ~$HG_EDITOR~.

* Using With-Editor as a library

This section describes how to use the ~with-editor~ library /outside/ of
Magit to teach another package how to have its child processes call
home, just like Magit does.  You don't need to know any of this just
to create commits using Magit.  You can also ignore this if you use
~with-editor~ outside of Magit, but only as an end-user.

For information about interactive use and options that affect both
interactive and non-interactive use, see [[*Using the With-Editor
package]].

- Macro: with-editor &rest body

  This macro arranges for the ~emacsclient~ or the sleeping editor to be
  used as the editor of child processes, effectively teaching them to
  call home to the current Emacs instance when they require that the
  user edits a file.

  This is essentially done by establishing a local binding for
  ~process-environment~ and changing the value of the ~$EDITOR~
  environment variable in that scope.  This affects all asynchronous
  processes started by forms (dynamically) inside BODY.

- Function: with-editor-set-process-filter process filter

  This function is like ~set-process-filter~ but ensures that adding the
  new FILTER does not remove the ~with-editor-process-filter~.  This is
  done by wrapping the two filter functions using a lambda, which
  becomes the actual filter.  It calls ~with-editor-process-filter~
  first, passing ~t~ as NO-STANDARD-FILTER.  Then it calls FILTER.

* Debugging

With-Editor tries very hard to locate a suitable ~emacsclient~
executable, and then sets option ~with-editor-emacsclient-executable~
accordingly.  In very rare cases this fails.  When it does fail, then
the most likely reason is that someone found yet another way to
package Emacs (most likely on macOS) without putting the executable on
~$PATH~, and we have to add another kludge to find it anyway.

If you are having problems using ~with-editor~, e.g. you cannot commit
in Magit, then please open a new issue at
https://github.com/magit/with-editor/issues and provide information
about your Emacs installation.  Most importantly how did you install
Emacs and what is the output of ~M-x with-editor-debug RET~.

# LocalWords: LocalWords
# LocalWords: Magit Emacs emacsclient FreeBSD macOS texinfo
# LocalWords: async eval hg init performant rebase startup

# Local Variables:
# eval: (require 'ox-texinfo+ nil t)
# End:
* _ Copying
:PROPERTIES:
:COPYING:    t
:END:

#+BEGIN_QUOTE
Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li>

You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any
later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
#+END_QUOTE

* _ :ignore:

# IMPORTANT: Also update ORG_ARGS and ORG_EVAL in the Makefile.
# Local Variables:
# eval: (require 'ox-extra nil t)
# eval: (require 'ox-texinfo+ nil t)
# eval: (and (featurep 'ox-extra) (ox-extras-activate '(ignore-headlines)))
# indent-tabs-mode: nil
# org-src-preserve-indentation: nil
# End: