241 lines
8.9 KiB
Org Mode
241 lines
8.9 KiB
Org Mode
#+TITLE: Shell layer
|
||
|
||
#+TAGS: layer|tool
|
||
|
||
[[file:img/shell.png]]
|
||
|
||
* Table of Contents :TOC_5_gh:noexport:
|
||
- [[#description][Description]]
|
||
- [[#features][Features:]]
|
||
- [[#install][Install]]
|
||
- [[#configuration][Configuration]]
|
||
- [[#default-shell][Default shell]]
|
||
- [[#default-shell-position-width-and-height][Default shell position, width, and height]]
|
||
- [[#set-shell-for-term-and-ansi-term][Set shell for term and ansi-term]]
|
||
- [[#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]]
|
||
- [[#eshell][Eshell]]
|
||
- [[#key-bindings][Key bindings]]
|
||
- [[#multi-term][Multi-term]]
|
||
- [[#eshell-1][Eshell]]
|
||
|
||
* Description
|
||
This layer configures the various shells available in Emacs.
|
||
|
||
** Features:
|
||
- Shell integration
|
||
|
||
* 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.
|
||
|
||
* Configuration
|
||
** 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, 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
|
||
|
||
** 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
|
||
|
||
** 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
|
||
|
||
* 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 '~ | Open, close or go to the default shell |
|
||
| ~SPC p '~ | Open a shell in the project's root |
|
||
| ~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= |
|
||
| ~TAB~ | browse completion with =helm= |
|
||
| ~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.
|
||
*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 |
|
||
| ~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 or ivy buffer |
|