97 lines
4.8 KiB
Org Mode
97 lines
4.8 KiB
Org Mode
#+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]]
|
||
- [[#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.
|
||
|
||
** 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.
|
||
|
||
* 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.
|
||
|
||
** 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
|
||
|
||
* 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 |
|