349 lines
13 KiB
Org Mode
349 lines
13 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]]
|
||
- [[#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]]
|
||
|
||
* 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=
|
||
- =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 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
|