doomemacs/modules/completion/ivy/README.org

completion/ivy

• Description
  • Module Flags
  • Plugins
  • Hacks
• Prerequisites
  • Install
    • MacOS
    • Arch Linux
    • openSUSE
• 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 depends on:

• ripgrep (rg)

Install

MacOS

brew install ripgrep

Arch Linux

sudo pacman --needed --noconfirm -S ripgrep

openSUSE

sudo zypper install ripgrep

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