:completion ivy

A search engine for snipers

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

1.1. Maintainers

This module has no dedicated maintainers. Become a maintainer?

1.2. Module flags

Cause Ivy to display in a floating child frame, over Emacs.
Enable fuzzy completion for Ivy searches.
Enable file icons for switch-{buffer,project}/find-file counsel commands.
Enable prescient filtering and sorting for Ivy searches.

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

2. Prerequisites

This module has no direct prerequisites.

3. Usage

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:

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

Keybind Description
SPC p f or SPC SPC Jump to file in project
SPC f f or SPC . Jump to file from current directory
SPC s i Jump to symbol in file

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

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


3.3. In-buffer searching

The swiper package provides an interactive buffer search powered by ivy. It can be invoked with:

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

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

3.4. Ivy integration for various completing commands

3.4.1. General

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

3.4.2. Jump to files, buffers or projects

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

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

4. TODO Configuration

This module has no usage documentation yet. Write some?

4.1. TODO Enable fuzzy/non-fuzzy search for specific commands

4.2. TODO Change the position of the ivy childframe

5. TODO Troubleshooting

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

6. TODO Appendix

This module has no appendix yet. Write one?