82b6bd3159
Depending on the system, this can cause sorting to be disabled long before the performance hit would be felt, and it's not obvious that this is the reason.
199 lines
8.2 KiB
Org Mode
199 lines
8.2 KiB
Org Mode
#+title: :completion ivy
|
|
#+subtitle: Yesterday's lightest search engine
|
|
#+created: February 20, 2017
|
|
#+since: 2.0.0
|
|
|
|
* Description :unfold:
|
|
This module provides Ivy integration for a variety of Emacs commands, as well as
|
|
a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]].
|
|
|
|
#+begin_quote
|
|
I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's
|
|
lighter, simpler and faster in many cases.
|
|
#+end_quote
|
|
|
|
** Maintainers
|
|
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
|
|
|
|
** Module flags
|
|
- +childframe ::
|
|
Display Ivy windows in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an popup buffer. *Requires
|
|
GUI Emacs.*
|
|
- +fuzzy ::
|
|
Enable fuzzy completion for Ivy searches.
|
|
- +icons ::
|
|
Enable file icons for switch-{buffer,project}/find-file commands.
|
|
- +prescient ::
|
|
Enable prescient filtering and sorting for Ivy searches.
|
|
|
|
** Packages
|
|
- [[doom-package:nerd-icons-ivy]]* if [[doom-module:+icons]]
|
|
- [[doom-package:amx]]
|
|
- [[doom-package:counsel]]
|
|
- [[doom-package:counsel-projectile]]
|
|
- [[doom-package:flx]]* if [[doom-module:+fuzzy]]
|
|
- [[doom-package:ivy]]
|
|
- [[doom-package:ivy-hydra]]
|
|
- [[doom-package:ivy-posframe]]* if [[doom-module:+childframe]]
|
|
- [[doom-package:ivy-rich]]
|
|
- [[doom-package:prescient]]* if [[doom-module:+prescient]]
|
|
- [[doom-package:swiper]]
|
|
- [[doom-package:wgrep]]
|
|
|
|
** Hacks
|
|
- Functions with ivy/counsel equivalents have been globally remapped (like
|
|
~find-file~ => ~counsel-find-file~). So a keybinding to ~find-file~ will
|
|
invoke ~counsel-find-file~ instead.
|
|
- ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex
|
|
command)
|
|
|
|
** TODO Changelog
|
|
# This section will be machine generated. Don't edit it by hand.
|
|
/This module does not have a changelog yet./
|
|
|
|
* Installation
|
|
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
|
|
|
This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]], which is a hard dependency of
|
|
Doom itself, so you should already have it installed.
|
|
|
|
Otherwise, Counsel (an Ivy plugin) provides many commands to interface with a
|
|
variety of programs from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][pass]] and /much/ more. These
|
|
programs are optional for this module, but must be installed if you intend to
|
|
use their associated Helm command or plugin.
|
|
|
|
* TODO Usage
|
|
#+begin_quote
|
|
/This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
[[doom-package:ivy]] is a /large/ framework for completing things. Covering all its features is
|
|
not within the scope of this module's documentation, so only its highlights will
|
|
be covered here.
|
|
|
|
** Jump-to navigation
|
|
Inspired by Sublime Text's jump-to-anywhere, CtrlP/Unite in Vim, and Textmate's
|
|
Command-T, this module provides similar functionality by bringing [[doom-package:projectile]] and
|
|
[[doom-package:ivy]] together.
|
|
|
|
https://assets.doomemacs.org/completion/ivy/projectile.png
|
|
|
|
| Keybind | Description |
|
|
|------------------+-------------------------------------|
|
|
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project |
|
|
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory |
|
|
| [[kbd:][SPC s i]] | Jump to symbol in file |
|
|
|
|
** Project search & replace
|
|
This module provides interactive text search and replace using ripgrep.
|
|
|
|
| Keybind | Description |
|
|
|---------+--------------------------|
|
|
| [[kbd:][SPC s p]] | Search project |
|
|
| [[kbd:][SPC s P]] | Search another project |
|
|
| [[kbd:][SPC s d]] | Search this directory |
|
|
| [[kbd:][SPC s D]] | Search another directory |
|
|
|
|
https://assets.doomemacs.org/completion/ivy/search.png
|
|
|
|
Prefixing these keys with the universal argument (=SPC u= for evil users; =C-u=
|
|
otherwise) changes the behavior of these commands, instructing the underlying
|
|
search engine to include ignored files.
|
|
|
|
This module also provides Ex Commands for evil users:
|
|
| Ex command | Description |
|
|
|------------------------+------------------------------------------------------------------|
|
|
| ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) |
|
|
| ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) |
|
|
|
|
The optional `!` is equivalent to the universal argument for the previous
|
|
commands.
|
|
|
|
-----
|
|
|
|
These keybindings are available while a search is active:
|
|
| Keybind | Description |
|
|
|---------+-----------------------------------------------|
|
|
| [[kbd:][C-c C-o]] | Open a buffer with your search results |
|
|
| [[kbd:][C-c C-e]] | Open a writable buffer of your search results |
|
|
| [[kbd:][C-SPC]] | Preview the current candidate |
|
|
| [[kbd:][C-RET]] | Open the selected candidate in other-window |
|
|
|
|
Changes to the resulting wgrep buffer (opened by [[kbd:][C-c C-e]]) can be committed with
|
|
[[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]] (alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users).
|
|
|
|
https://assets.doomemacs.org/completion/ivy/search-replace.png
|
|
|
|
** In-buffer searching
|
|
The [[doom-package:swiper]] package provides an interactive buffer search powered by ivy. It
|
|
can be invoked with:
|
|
|
|
- [[kbd:][SPC s s]] (~swiper-isearch~)
|
|
- [[kbd:][SPC s S]] (~swiper-isearch-thing-at-point~)
|
|
- [[kbd:][SPC s b]] (~swiper~)
|
|
- ~:sw[iper] [QUERY]~
|
|
|
|
https://assets.doomemacs.org/completion/ivy/swiper.png
|
|
|
|
A wgrep buffer can be opened from swiper with [[kbd:][C-c C-e]].
|
|
|
|
** Ivy integration for various completing commands
|
|
*** General
|
|
| Keybind | Description |
|
|
|------------+---------------------------|
|
|
| [[kbd:][M-x]], [[kbd:][SPC :]] | Smarter, smex-powered M-x |
|
|
| [[kbd:][SPC ']] | Resume last ivy session |
|
|
|
|
*** Jump to files, buffers or projects
|
|
| Keybind | Description |
|
|
|------------------+---------------------------------------|
|
|
| [[kbd:][SPC RET]] | Find bookmark |
|
|
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory |
|
|
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project |
|
|
| [[kbd:][SPC f r]] | Find recently opened file |
|
|
| [[kbd:][SPC p p]] | Open another project |
|
|
| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace |
|
|
| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer |
|
|
|
|
*** Search
|
|
| Keybind | Description |
|
|
|---------+-------------------------------------------|
|
|
| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project |
|
|
| [[kbd:][SPC s b]] | Search the current buffer |
|
|
| [[kbd:][SPC s d]] | Search this directory |
|
|
| [[kbd:][SPC s D]] | Search another directory |
|
|
| [[kbd:][SPC s i]] | Search for symbol in current buffer |
|
|
| [[kbd:][SPC s p]] | Search project |
|
|
| [[kbd:][SPC s P]] | Search another project |
|
|
| [[kbd:][SPC s s]] | Search the current buffer (incrementally) |
|
|
|
|
* TODO Configuration
|
|
#+begin_quote
|
|
/This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
** TODO Enable fuzzy/non-fuzzy search for specific commands
|
|
** TODO Change the position of the ivy childframe
|
|
|
|
* TODO Troubleshooting
|
|
** Sorting is not applied at all sometimes
|
|
If the number of candidates is greater than ~ivy-sort-max-size~, sorting will be
|
|
disabled completely. Doom lowers the default value to prevent performance
|
|
issues, so increasing the value may fix your issue:
|
|
#+begin_src elisp
|
|
;;; add to $DOOMDIR/config.el
|
|
(after! ivy
|
|
(setq ivy-sort-max-size 30000)) ; Doom sets this to 7500, but Ivy's default is 30k
|
|
#+end_src
|
|
|
|
|
|
* Frequently asked questions
|
|
[[doom-suggest-faq:][Ask a question?]]
|
|
|
|
** Helm vs Ivy vs Ido vs Vertico
|
|
See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]].
|
|
|
|
* TODO Appendix
|
|
#+begin_quote
|
|
This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
|
#+end_quote
|