doomemacs/modules/completion/ivy/README.org

:completion ivy

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
• Usage
  • Jump-to navigation
  • Project search & replace
  • In-buffer searching
  • Ivy integration for various completing commands
    • General
    • Jump to files, buffers or projects
    • Search
• Configuration
  • Enable fuzzy/non-fuzzy search for specific commands
  • Change the position of the ivy childframe
• Troubleshooting
• Frequently asked questions
  • Helm vs Ivy vs Ido vs Vertico
• Appendix

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

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

TODO 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]

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)

TODO Configuration

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

TODO Enable fuzzy/non-fuzzy search for specific commands

TODO Change the position of the ivy childframe

TODO Troubleshooting

There are no known problems with this module. Report one?

Frequently asked questions

Ask a question?

Helm vs Ivy vs Ido vs Vertico

See this answer.

TODO Appendix

󱌣 This module has no appendix yet. Write one?