116 lines
6.7 KiB
Org Mode
116 lines
6.7 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]]
|
|
- [[#colorsfaces][Colors/Faces]]
|
|
|
|
* 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.
|
|
- =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
|
|
|
|
* 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-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~)) |
|
|
|
|
** Transient state
|
|
Press ~M-SPC~ (~m-M-SPC~ [[https://github.com/syl20bnr/spacemacs/blob/cb48ec74c1f401bd2945760799633c0e81e69088/doc/CONVENTIONS.org#transient-state][on macOS]]) 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= |
|