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

#+TITLE: Ivy layer

* Table of Contents                                         :TOC_4_gh:noexport:
 - [[#description][Description]]
 - [[#install][Install]]
 - [[#configuration][Configuration]]
 - [[#key-bindings][Key Bindings]]
   - [[#transient-state][Transient state]]

* Description
This layer enables Ivy for completion. It will replace the default completion by
[[https://github.com/emacs-helm/helm][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.

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

* Configuration
You can customize ivy with the following variables:

- =ivy-wrap= Whether C-n and C-p should wrap-around when at the 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.

* Key Bindings
If you choose =ivy= as completion system, make sure to read the [[http://oremacs.com/swiper/][official manual]].
In case you don't want to read everything, at least familiarise with
[[http://oremacs.com/swiper/#minibuffer-key-bindings][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-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                                                                                     |

** Transient state
Press ~M-SPC~ anytime in Ivy to get into the transient state.

| Key Binding | Description                                             |
|-------------+---------------------------------------------------------|
| ~j~         | select next candidate                                   |
| ~k~         | select previous candidate                               |
| ~d~         | call default action on candidate                        |
| ~g~         | the same as ~d~ but doesn't close completion minibuffer |
| ~o~         | leave transient state                                   |