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

#+TITLE: Ivy layer

#+TAGS: completion|layer

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
- [[#configuration][Configuration]]
  - [[#general][General]]
  - [[#advanced-buffer-information][Advanced buffer information]]
  - [[#icons][Icons]]
- [[#key-bindings][Key bindings]]
  - [[#markunmark-candidates][Mark/unmark candidates]]
  - [[#transient-state][Transient state]]
  - [[#colorsfaces][Colors/Faces]]
  - [[#search-files-with-ivy][Search files with ivy]]

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

** 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
  [[https://github.com/abo-abo/swiper/wiki/ido-style-folder-navigation][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.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (ivy :variables ivy-enable-advanced-buffer-information t)))
#+END_SRC

** Icons
To display icons with [[https://github.com/seagle0128/all-the-icons-ivy-rich][all-the-icons-ivy-rich]], set the layer variable
=ivy-enable-icons= to =t=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (ivy :variables ivy-enable-icons t)))
#+END_SRC

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 [[https://github.com/seagle0128/all-the-icons-ivy-rich][here]].

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

** Mark/unmark candidates

| Key binding | Description                                             |
|-------------+---------------------------------------------------------|
| ~C-.~       | Mark candidate and move to next line                    |
| ~C ,~       | Unmark the selected candidate and move to the next one. |
| ~C-<~       | Move to the previous candidate and unmark it.           |
| ~C->~       | Toggle mark for all narrowed candidates.                |

** Transient state
Press ~M-SPC~ (~s-M-SPC~ [[https://github.com/syl20bnr/spacemacs/blob/cb48ec74c1f401bd2945760799633c0e81e69088/doc/CONVENTIONS.org#transient-state][on macOS]]) or ~C-o~ anytime in Ivy to get into the transient state. Additional actions are found in [[https://oremacs.com/swiper/#minibuffer-key-bindings][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= |

** Search files with ivy
=ripgrep= is recommended and =Spacemacs= will pick it up as the default seach
app if found. To pass parameters to =ripgrep= use double dash then everything
after it is treated as parameters for search app.

For example:

#+BEGIN_EXAMPLE
  phrase I want to search -- -t lisp
#+END_EXAMPLE

will search only on lisp files.

Commands available while browsing the search result:

| Key binding      | Description                      |
|------------------+----------------------------------|
| ~C-SPC~ or ~C-l~ | Preview result                   |
| ~C-x C-d~        | Change search folder             |
| ~M-q~            | =counsel-git-grep-query-replace= |
| ~C-c C-o~        | =ivy-occur=                      |
| ~C-c C-e~        | Spacemacs's =counsel-edit=       |

When you =M-o= on the result list of =counsel-find-file= and file search result
you have these following extra actions:

| Key binding | Description                     |
|-------------+---------------------------------|
| ~f~         | =find-file-other-frame=         |
| ~j~         | =find-file-other-window=        |
| ~v~         | =spacemacs/find-file-vsplit=    |
| ~s~         | =spacemacs/find-file-split=     |
| ~l~         | =find-file-literally=           |
| ~d~         | =spacemacs/delete-file-confirm= |
| ~r~         | =spacemacs/rename-file=         |