doomemacs/modules/completion/ivy/README.org

completion/ivy

• Description
  • Module Flags
  • Plugins
  • Hacks
• Prerequisites
• Features
  • 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

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.

Module Flags

• +fuzzy Enables fuzzy completion for Ivy searches.
• +prescient Enables prescient filtering and sorting for Ivy searches.
• +childframe Causes Ivy to display in a floating child frame, above Emacs.
• +icons Enables file icons for switch-{buffer,project}/find-file counsel commands.

Plugins

• ivy
• counsel
• counsel-projectile
• swiper
• ivy-hydra
• ivy-rich
• wgrep
• amx
• flx* (+fuzzy)
• prescient* (+prescient)
• ivy-posframe* (+childframe)
• all-the-icons-ivy* (+icons)

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)

Prerequisites

This module has no prerequisites.

Features

Ivy and its ilk are large plugins. Covering everything about them is outside of this documentation's scope, so only Doom-specific Ivy features are listed 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 projectile and 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 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)

Configuration

TODO Enable fuzzy/non-fuzzy search for specific commands

TODO Change the position of the ivy childframe

TODO Troubleshooting