README.org

:completion ivy

Description

This module provides Ivy integration for a variety of Emacs commands, as well as a unified interface for project search and replace, powered by ripgrep.

I prefer ivy over ido for its flexibility. I prefer ivy over helm because it’s lighter, simpler and faster in many cases.

Maintainers

This module has no dedicated maintainers. Become a maintainer?

Module flags

+childframe

Display Ivy windows in a 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)

Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

This module has only one requirement: 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 fzf to Dash docsets to 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.

Usage

󱌣 This module’s usage documentation is incomplete. Complete it?

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
SPC p f, SPC SPC	Jump to file in project
SPC f f, SPC .	Jump to file from current directory
SPC s i	Jump to symbol in file

Project search & replace

This module provides interactive text search and replace using ripgrep.

Keybind	Description
SPC s p	Search project
SPC s P	Search another project
SPC s d	Search this directory
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
C-c C-o	Open a buffer with your search results
C-c C-e	Open a writable buffer of your search results
C-SPC	Preview the current candidate
C-RET	Open the selected candidate in other-window

Changes to the resulting wgrep buffer (opened by C-c C-e) can be committed with C-c C-c and aborted with C-c C-k (alternatively ZZ and 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:

• SPC s s (swiper-isearch)
• SPC s S (swiper-isearch-thing-at-point)
• SPC s b (swiper)
• :sw[iper] [QUERY]

https://assets.doomemacs.org/completion/ivy/swiper.png

A wgrep buffer can be opened from swiper with C-c C-e.

Ivy integration for various completing commands

General

Keybind	Description
M-x, SPC :	Smarter, smex-powered M-x
SPC ’	Resume last ivy session

Jump to files, buffers or projects

Keybind	Description
SPC RET	Find bookmark
SPC f f, SPC .	Browse from current directory
SPC p f, SPC SPC	Find file in project
SPC f r	Find recently opened file
SPC p p	Open another project
SPC b b, SPC ,	Switch to buffer in current workspace
SPC b B, SPC <	Switch to buffer

Search

Keybind	Description
SPC p t	List all TODO/FIXMEs in project
SPC s b	Search the current buffer
SPC s d	Search this directory
SPC s D	Search another directory
SPC s i	Search for symbol in current buffer
SPC s p	Search project
SPC s P	Search another project
SPC s s	Search the current buffer (incrementally)

Configuration

󱌣 This module’s configuration documentation is incomplete. Complete it?

Enable fuzzy/non-fuzzy search for specific commands

Change the position of the ivy childframe

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:

;;; add to $DOOMDIR/config.el
(after! ivy
  (setq ivy-sort-max-size 30000))  ; Doom sets this to 7500, but Ivy's default is 30k

Frequently asked questions

Ask a question?

Helm vs Ivy vs Ido vs Vertico

See this answer.

Appendix

󱌣 This module has no appendix yet. Write one?