spacemacs/layers/+tools/shell/README.org

#+TITLE: Shell layer

#+TAGS: layer|tool

[[file:img/shell.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#install-vterm][Install vterm]]
    - [[#check-that-your-emacs-supports-dynamic-modules][Check that your Emacs supports dynamic modules]]
    - [[#install-cmake-311-or-higher][Install CMake 3.11 or higher]]
      - [[#macos][macOS]]
      - [[#ubuntu][Ubuntu]]
    - [[#install-libtool][Install libtool]]
      - [[#ubuntu-1][Ubuntu]]
    - [[#install-libvterm-optional][Install libvterm (Optional)]]
      - [[#macos-1][macOS]]
      - [[#linux][Linux]]
      - [[#windows][Windows]]
- [[#configuration][Configuration]]
  - [[#default-shell][Default shell]]
  - [[#default-shell-position-width-and-height][Default shell position, width, and height]]
  - [[#external-terminal-emulator][External terminal emulator]]
  - [[#set-shell-for-term-ansi-term-and-vterm][Set shell for term, ansi-term and vterm]]
  - [[#set-shell-for-multi-term][Set shell for multi-term]]
  - [[#width-of-the-shell-popup-buffers][Width of the shell popup buffers]]
  - [[#enable-em-smart-in-eshell][Enable em-smart in Eshell]]
  - [[#protect-your-eshell-prompt][Protect your Eshell prompt]]
  - [[#fish-shell-and-ansi-term][Fish shell and ansi-term]]
  - [[#close-window-with-terminal][Close window with terminal]]
- [[#eshell][Eshell]]
- [[#key-bindings][Key bindings]]
  - [[#multi-term][Multi-term]]
  - [[#eshell-1][Eshell]]
  - [[#vterm][vterm]]
  - [[#multi-vterm][Multi-vterm]]

* Description
This layer configures the various shells available in Emacs.

** Features:
- Shell integration
- Running external terminal emulator in current/project directory

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =shell= to the existing =dotspacemacs-configuration-layers= list in this
file.

** Install vterm
=vterm= is the latest addition to Emacs' set of terminal emulators and the only
one to be implemented in C, leveraging =libvterm=. It is the only one in Emacs
at the moment to be as fast as a standalone terminal with full support for
=ncurses=, =vim=, =htop= and the likes.

On its first run, =vterm= will automatically compile its dynamic library, for
which dependencies are needed. For more details, head to the [[https://github.com/akermu/emacs-libvterm][official docs]].

*** Check that your Emacs supports dynamic modules
You can check if your Emacs supports loading dynamic libraries by checking if
the =system-configuration-features= variable contains the string =MODULES=. If
not, you need to get a version of Emacs that supports it or compile it from
source supplying the =./configure --with-module= option at configure time.

*** Install CMake 3.11 or higher
**** macOS
#+BEGIN_SRC shell
  brew install cmake
#+END_SRC

**** Ubuntu
#+BEGIN_SRC shell
  sudo apt install cmake
#+END_SRC

*** Install libtool
If the =libtool= command does not exist in your system (usually in
=/usr/bin/libtool=), you need to install it:

**** Ubuntu
#+BEGIN_SRC shell
  sudo apt install libtool-bin
#+END_SRC

*** Install libvterm (Optional)
**** macOS
#+BEGIN_SRC shell
  brew install libvterm
#+END_SRC

**** Linux
This library can be found in the official repositories of most distributions
(e.g., Arch, Debian, Fedora, Gentoo, openSUSE, Ubuntu). If not available, it
will be downloaded during the compilation process. Some distributions
(e.g. Ubuntu 18.04) have versions of libvterm that are too old.
If you find compilation errors related to VTERM_COLOR, you should
not use your system libvterm.

**** Windows
Not supported at the moment, [[https://github.com/akermu/emacs-libvterm/issues/12][but possibly coming up]].

* Configuration
** Default shell
Emacs supports five types of shells/terminals:
- the Emacs shell (eshell)
- the inferior shell
- the terminal emulator
- the ANSI terminal emulator
- the vterm terminal emulator based on the C library libvterm

You can find a quick introductions to them [[https://www.masteringemacs.org/article/running-shells-in-emacs-overview][here]].

To define the default shell you can set the layer variable =shell-default-shell=
to the following variables:
- =eshell= (default on Windows)
- =shell=
- =term=
- =ansi-term= (default on Linux/macOS)
- =multi-term=
- =multi-vterm=
- =vterm=

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((shell :variables shell-default-shell 'eshell)))
#+END_SRC

The default shell is quickly accessible via a the default shortcut key ~SPC '​~.

** Default shell position, width, and height
It is possible to choose where the shell should pop up by setting the variable
=shell-default-position= to either =top=, =bottom=, =left=, =right=, or =full=.
Default value is =bottom=. It is also possible to set the default height in
percents with the variable =shell-default-height=. Default value is =30=. You
can also set a default width in percents with the variable
=shell-default-width=, which has a default value of 30 and will take effect if
your shell is positioned on the left or the right.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((shell :variables
             shell-default-position 'bottom
             shell-default-height 30)))

  (setq-default dotspacemacs-configuration-layers
    '((shell :variables
             shell-default-position 'right
             shell-default-width 40)))
#+END_SRC

** External terminal emulator
This layer supports opening an external terminal emulator using [[https://github.com/davidshepherd7/terminal-here][terminal-here]].
By default =terminal-here= finds an appropriate default shell for you.
If this does not work please check the package documentation how to
change it.

** Set shell for term, ansi-term and vterm
The default shell can be set by setting the variable =shell-default-term-shell=.
Default value is =/bin/bash=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((shell :variables shell-default-term-shell "/bin/bash")))
#+END_SRC

** Set shell for multi-term
The default shell can be set by setting the variable =multi-term-program=.
Default value is =/bin/bash=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((shell :variables multi-term-program "/bin/bash")))
#+END_SRC

** Width of the shell popup buffers
By default the popup buffer spans the full width of the current frame, if
you prefer to spans only the width of the current window then set the
layer variable =shell-default-full-span= to nil.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((shell :variables shell-default-full-span nil)))
#+END_SRC

** Enable em-smart in Eshell
From the =em-smart= documentation:

#+BEGIN_QUOTE
  The best way to get a sense of what this code is trying to do is by
  using it. Basically, the philosophy represents a blend between the
  ease of use of modern day shells, and the review-before-you-proceed
  mentality of Plan 9's 9term.
#+END_QUOTE

In a nutshell, when =em-smart= is enabled point won't jump at the end of the
buffer when a command is executed, it will stay at the same command prompt used
to execute the command. This allows to quickly edit the last command in the case
of a mistake. If there is no mistake and you directly type a new command then
the prompt will jump to the next prompt at the end of the buffer.

To enable =em-smart= put the following layer variable to non-nil:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((shell :variables shell-enable-smart-eshell t)))
#+END_SRC

** Protect your Eshell prompt
Comint mode (Shell mode) has good support for Evil mode as it inhibits movement
commands over the prompt. This has the added benefit that Evil mode functions
work sensibly. E.g. you can press ~cc~ in normal state i.e.
=evil-change-whole-line= to kill the current input and start typing a new
command. In Eshell you also kill the prompt, which is often unintended.

By default this layer also protects the =eshell= prompt. If you want to
disable this protection you can set the variable =shell-protect-eshell-prompt=
to nil.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((shell :variables shell-protect-eshell-prompt nil)))
#+END_SRC

** Fish shell and ansi-term
Making =fish= shell to work with =ansi-term= may be a challenge, here are
some pointers to save you time to setup your environment correctly.

First be sure =~/.terminfo= is setup correctly by running:

#+BEGIN_SRC fish
  tic -o ~/.terminfo $TERMINFO/e/eterm-color.ti
#+END_SRC

You can locate the =eterm-colors.ti= file with:

#+BEGIN_SRC fish
  locate eterm-color.ti
#+END_SRC

Then setup your fish configuration file (usually at =~/.config/fish/config.fish=)

#+BEGIN_SRC fish
  # emacs ansi-term support
  if test -n "$EMACS"
    set -x TERM eterm-color
  end

  # this function may be required
  function fish_title
    true
  end
#+END_SRC

Finally you may need to toggle truncated lines for some prompts to work
correctly, in the function =dotspacemacs/user-config= of your dotfile add:

#+BEGIN_SRC emacs-lisp
  (add-hook 'term-mode-hook 'spacemacs/toggle-truncate-lines-on)
#+END_SRC

** Close window with terminal
If you want its window to close when the terminal terminates, set the following
layer variable to non-nil:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((shell :variables close-window-with-terminal t)))
#+END_SRC

This is only applied to =term= and =ansi-term= modes.

* Eshell
Some advanced configuration is setup for =eshell= in this layer:
- some elisp functions aliases for quick access
  - =s= for =magit-status= in the current directory (when the =git= layer is
    installed)
  - =d= for =dired=
  - =e= to find a file via a new buffer
  - =z= for quickly jumping to a previously visited directory
- optional configuration for =em-smart= (see =Install= section for more info)
- support for visual commands via =em-term=
- working directory sensitive prompt via [[https://github.com/kaihaosw/eshell-prompt-extras][eshell-prompt-extras]]
- advanced help support via =esh-help= (enable =el-doc= support in eshell)
- add support for auto-completion via =company= (when the =auto-completion=
  layer is installed)
- pressing ~i~ in normal state will automatically jump to the prompt

* Key bindings

| Key binding   | Description                                              |
|---------------+----------------------------------------------------------|
| ~SPC '​~       | Toggle pop-shell with your default shell                 |
| ~SPC "​~       | Open external terminal emulator in current directory     |
| ~SPC a t s e~ | Toggle pop-shell with =eshell=                           |
| ~SPC a t s i~ | Toggle pop-shell with =shell=                            |
| ~SPC a t s m~ | Toggle pop-shell with =multi-term=                       |
| ~SPC a t s M~ | Toggle pop-shell with =multi-vterm=                      |
| ~SPC a t s t~ | Toggle pop-shell with =ansi-term=                        |
| ~SPC a t s T~ | Toggle pop-shell with =term=                             |
| ~SPC a t s v~ | Toggle pop-shell with =vterm=                            |
|---------------+----------------------------------------------------------|
| ~SPC p '​~     | Toggle pop-shell with your default shell in project root |
| ~SPC p "​~     | Open external terminal emulator in project root          |
| ~SPC p $~     | Open a new buffer with default shell in project root     |
|---------------+----------------------------------------------------------|
| ~TAB~         | In a shell buffer, browse completions                    |
| ~SPC m H~     | In =shell= or =eshell=, browse history                   |
| ~C-j~         | Next item in history                                     |
| ~C-k~         | Previous item in history                                 |

*Note:* You can open multiple shells using a numerical prefix argument,
for instance pressing ~2 SPC '​~ will a second default shell, the
number of shell is indicated on the mode-line.

*Note:* Use the universal prefix argument ~SPC u SPC '​~ to open the shell
in the current buffer instead of a popup.

** Multi-term

| Key binding            | Description                    |
|------------------------+--------------------------------|
| ~SPC m c~              | create a new multi-term        |
| ~SPC m C~              | switch multi-term char mode    |
| ~SPC m l~              | switch multi-term to line mode |
| ~SPC m n~              | go to next multi-term          |
| ~SPC m N~ or ~SPC m p~ | go to previous multi-term      |

** Eshell

| Key binding        | Description                  |
|--------------------+------------------------------|
| ~SPC m H~ or ~M-l~ | search shell command history |

** vterm

| Key binding | Description                   |
|-------------+-------------------------------|
| ~M-r~       | search shell command history* |

Note*: ~M-r~ will only be bound to search for the command history when the
variable =spacemacs-vterm-history-file-location= is set to the path to your
shell history file.

For example with bash

#+BEGIN_SRC elisp
  (shell :variables
         spacemacs-vterm-history-file-location "~/.bash_history")
#+END_SRC

** Multi-vterm

| Key binding            | Description                |
|------------------------+----------------------------|
| ~SPC m c~              | create a new multi-vterm   |
| ~SPC m n~              | go to next multi-vterm     |
| ~SPC m N~ or ~SPC m p~ | go to previous multi-vterm |
| ~SPC m r~              | rename vterm buffer        |