spacemacs/contrib/shell/README.org

Shell contribution layer for Spacemacs

• Table of Contents
• Description
• Install
  • Layer
  • Default shell
  • Default shell position and height
  • Set shell for term and ansi-term
  • Enable em-smart in Eshell
  • Protect your Eshell prompt
• Eshell
• Key bindings
  • Multi-term
  • Eshell

Table of Contents   TOC@4

• Description

• Install

  • Layer
  • Default shell
  • Default shell position and height
  • Set shell for term and ansi-term
  • Enable em-smart in Eshell
  • Protect your Eshell prompt
• Eshell

• Key bindings

  • Multi-term
  • Eshell

Description

This layer configures the various shells available in Emacs.

Install

Layer

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

  (setq-default dotspacemacs-configuration-layers '(shell))

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

(setq-default dotspacemacs-configuration-layers
  '(shell :variables shell-default-shell 'eshell))

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.

  (setq-default dotspacemacs-configuration-layers
    '(shell :variables
            shell-default-position 'bottom
            shell-default-height 30))

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.

  (setq-default dotspacemacs-configuration-layers
    '(shell :variables shell-default-term-shell "/bin/bash"))

Enable em-smart in Eshell

From the em-smart documentation:

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.

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:

  (setq-default dotspacemacs-configuration-layers
    '(shell :variables shell-enable-smart-eshell t))

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.

  (setq-default dotspacemacs-configuration-layers
    '(shell :variables shell-protect-eshell-prompt nil))

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