spacemacs/contrib/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]]
 - [[#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

* 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 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 |