spacemacs/layers/+completion/ivy/README.org

Ivy layer

• Description
  • Features:
• Install
• Configuration
  • General
  • Advanced buffer information
  • Icons
• Key bindings
  • Transient state
  • Colors/Faces

Description

This layer enables Ivy for completion. It will replace the default completion by Helm.

These completion systems are the central control towers of Spacemacs, they are used to manage buffers, projects, search results, configuration layers, toggles and more…

Mastering your choice of completion system will make you a Spacemacs power user.

Features:

• Project wide grep like text search via search-auto
• Project wide text replacements using counsel-imenu
• Buffer wide dynamic text search via swiper
• Detailed configuration parameters for ivy appearance
• Intuitive transient state
• Advanced buffer information with ivy-rich

Install

To use this configuration layer, add it to your ~/.spacemacs. You will need to add ivy to the existing dotspacemacs-configuration-layers list in this file.

Make sure that the other completion layers: compleseus and helm are removed or commented out in the dotspacemacs-configuration-layers list. Or add ivy below the other completion layers. Spacemacs uses the completion layer that's listed last.

Configuration

General

You can customize ivy with the following variables:

• ivy-wrap Whether C-n and C-p should wrap-around when at the first or last candidate. The default value is nil.
• ivy-extra-directories Setting this to nil hides . and .. directories from file name completion. You can still go up a directory up by DEL. The default value is ("../", "./").
• ivy-use-virtual-buffers Add bookmarks and recent files to buffer completion menu. The Spacemacs default is t.
• ivy-height The height of the minibuffer. The Spacemacs default is 15.
• ivy-use-selectable-prompt When non-nil, make the prompt line selectable like a candidate. The Spacemacs default value is t.
• ivy-re-builders-alist An alist of regex building functions for each collection function. See ivy documentation for possible choices. Use spacemacs/ivy--regex-plus instead of ivy--regex-plus to get correct highlighting in the search results of spacemacs/search-project-auto and similar search commands provided by Spacemacs.
• ivy-ret-visits-directory Whether RET and C-j should be swapped in ivy minibuffer so RET acts like Ido and descends into directory. It is described here (probably outdated). Default value is nil.

Advanced buffer information

To display more information about buffers set the layer variable ivy-enable-advanced-buffer-information to t which will enable ivy-rich.

Note that ivy-rich has been reported to be very slow on macOS. This feature is disabled by default.

  (setq-default dotspacemacs-configuration-layers '(
    (ivy :variables ivy-enable-advanced-buffer-information t)))

Icons

To display icons with all-the-icons-ivy-rich, set the layer variable ivy-enable-icons to t.

  (setq-default dotspacemacs-configuration-layers '(
    (ivy :variables ivy-enable-icons t)))

Because all-the-icons-ivy-rich depends on ivy-rich, the layer variable ivy-enable-advanced-buffer-information is automatically set to t when ivy icon display is enabled.

To display icons correctly, you should run M-x all-the-icons-install-fonts to install the necessary fonts.

More information about customizing all-the-icons-ivy-rich can be found here.

Key bindings

If you choose ivy as completion system, make sure to read the official manual. In case you don't want to read everything, at least familiarise with minibuffer key bindings.

Some useful key bindings are presented in the following table.

Key binding	Description
RET	call default action on current candidate
M-RET	the same as RET but doesn't close completion minibuffer
C-RET	when completing file names, selects the current directory candidate and starts a new completion session there, otherwise it is the same as ivy-done
C-SPC	try to preview file under point without leaving ivy
C-M-j	use current input immediately (this can be used to create a new file in Find File)
TAB	complete partially
M-o	show the list of valid actions on current candidate (then press any of described keys to execute it)
C-M-o	the same as M-o but doesn't close completion minibuffer
C-'	use avy to quickly select completion on current page (sometimes faster than using arrows)
<ESC>	close minibuffer
C-M-k	kill buffer (in ivy-switch-buffer (SPC b b))
C-M-k	kill buffer (in ivy-reverse-i-search (C-r at a prompt))

Transient state

Press M-SPC (s-M-SPC on macOS) anytime in Ivy to get into the transient state. Additional actions are found in the Hydra section of the official manual.

Key binding	Description
j	select next candidate
k	select previous candidate
d	call default action on candidate
f	call alternative action on candidate
g	the same as d but doesn't close completion minibuffer
o	leave transient state
m	mark candidate
u	unmark candidate
t	toggle marks

Colors/Faces

Key binding	Description
SPC C e	counsel-colors-emacs
SPC C f	counsel-colors-faces
SPC C w	counsel-colors-web
SPC h d F	counsel-describe-face