spacemacs/layers/shell/README.org

#+TITLE: Shell contribution layer for Spacemacs

[[file:img/shell.png]]

* Table of Contents                                                 :TOC@4:
 - [[#description][Description]]
 - [[#install][Install]]
     - [[#layer][Layer]]
     - [[#default-shell][Default shell]]
     - [[#default-shell-position-and-height][Default shell position and height]]
     - [[#set-shell-for-term-and-ansi-term][Set shell for term and ansi-term]]
     - [[#enable-em-smart-in-eshell][Enable em-smart in Eshell]]
     - [[#protect-your-eshell-prompt][Protect your Eshell prompt]]
 - [[#eshell][Eshell]]
 - [[#key-bindings][Key bindings]]
     - [[#multi-term][Multi-term]]
     - [[#eshell][Eshell]]

* Description

This layer configures the various shells available in Emacs.

* Install

** Layer

To use this contribution add it to your =~/.spacemacs=

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

** Default shell

Emacs supports three types of shell:
- the Emacs shell
- the inferior shell
- the terminal emulator
- the ANSI terminal emulator

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=
- =shell=
- =term=
- =ansi-term=
- =multi-term=

#+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 and height

It is possible to choose where the shell should pop up by setting the variable
=shell-default-position= to either =top=, =bottom= or =full=. It is not possible
to show it on the side for now. 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=.

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

** Set shell for term and ansi-term

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

** 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 the 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 =ehsell= 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

* 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
- 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/hiddenlotus/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 '~     | Open, close or go to the default shell                     |
| ~SPC a s e~ | Open, close or go to an =eshell=                           |
| ~SPC a s i~ | Open, close or go to a =shell=                             |
| ~SPC a s m~ | Open, close or go to a =multi-term=                        |
| ~SPC a s t~ | Open, close or go to a =ansi-term=                         |
| ~SPC a s T~ | Open, close or go to a =term=                              |
| ~SPC m H~   | browse history with =helm= (works in =eshell= and =shell=) |
| ~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.

** Multi-term

| Key Binding | Description                  |
|-------------+------------------------------|
| ~SPC m c~   | create a new multi-term      |
| ~SPC m n~   | go to next multi-term        |
| ~SPC m p~   | go to previous multi-term    |
| ~SPC p $ t~ | run multi-term shell in root |

** Eshell

| Key Binding        | Description                                |
|--------------------+--------------------------------------------|
| ~SPC m H~ or ~M-l~ | shell commands history using a helm buffer |