doomemacs/modules/completion/ivy

• :completion ivy
  • Install
    • MacOS
    • Arch Linux
  • Usage
    • Search & Replace
    • Jump-to-file project navigation
    • In-buffer searching
    • TODO-Task lookup
  • Appendix
    • Commands & Keybindings
    • Hacks

:completion ivy

This module adds the Ivy completion backend.

I prefer ivy over ido and helm, for its speed and simplicity. With ivy's help and some hackery, I get the following features:

• Project-wide search & replace powered by rg and ag
• Project jump-to navigation ala Command-T, Sublime Text's Jump-to-anywhere or Vim's CtrlP plugin.
• Ivy integration for M-x, imenu, recentf and others.
• A powerful, interactive in-buffer search using swiper.
• Ivy-powered TODO/FIXME navigation

Install

This module optionally depends on ripgrep and the_silver_searcher.

rg is faster, but its results aren't deterministic and it doesn't support multiline search or full PCRE, that's where ag is useful.

MacOS

brew install ripgrep the_silver_searcher

Arch Linux

sudo pacman --needed --noconfirm -S ripgrep the_silver_searcher

Usage

Search & Replace

A project-wide search can be performed with Ag (the silver searcher) or Rg (ripgrep) via their ex commands: :ag[!] and :rg[!] (or their current-directory counterparts :agcwd[!] and :rgcwd[!])

From this session, you can press Shift + Tab to create an writeable occur buffer in wgrep mode.

Make your modifications and press C-c C-c to commit them, or C-c C-k to abort.

Jump-to-file project navigation

Inspired by Sublime Text's jump-to-anywhere, Vim's CtrlP or Unite plugins, and Textmate's Command-T, a marriage of projectile and ivy makes this available to you in Emacs. Invoke it with <leader> / or counsel-projectile-find-file.

In-buffer searching

I prefer to use evil-search (invoked by pressing / in normal mode) when jumping small/moderate (or predictable) distances. On occasion I need more feedback, so I turn to swiper (available directly with M-x swiper RET, or via :sw[iper]).

TODO-Task lookup

I sprinkle my projects with TODO's & FIXME's. Using ivy and ripgrep, I wrote +ivy/tasks to help me navigate to them. It can be invoked via :todo[!] as well.

Appendix

Commands & Keybindings

Here is a list of my commonly used commands, their default keybinds (defined in private/hlissner/+bindings.el), and their corresponding ex command (defined in private/hlissner/+commands.el).

command	key / ex command	description
counsel-M-x	M-x	Smarter, smex-powered M-x
counsel-bookmark	<leader> b	Find bookmark
counsel-find-file	<leader> .	Browse from current directory
counsel-projectile-find-file	<leader> /	Find file in project
counsel-projectile-switch-project	<leader> p	Open another project
counsel-recentf	<leader> r	Find recently opened file
+ivy/switch-buffer	<leader> ,	Jump to buffer in current workspace
+ivy/switch-workspace-buffer	<leader> <	Jump to buffer across workspaces
+ivy:ag	:ag[!] [QUERY]	Search project (BANG = ignore gitignore)
+ivy:ag-cwd	:agcwd[!] [QUERY]	Search this directory (BANG = don't recurse into subdirectories)
+ivy:rg	:rg[!] [QUERY]	Search project (if BANG, ignore gitignore)
+ivy:rg-cwd	:rgcwd[!] [QUERY]	Search this directory (BANG = don't recurse into subdirectories)
+ivy:swiper	:sw[iper] [QUERY]	Search current buffer
+ivy:todo	:todo[!]	List all TODO/FIXMEs in project (or current file if BANG)

While in a search (e.g. invoked from +ivy:ag or +ivy:rg), these new keybindings are available to you:

key	description
<backtab>	Perform search/replace on the search results (open occur buffer in wgrep mode)
C-SPC	Preview the current candidate
M-RET	Open the selected candidate in other-window

Hacks

• Where possible, functions with ivy/counsel equivalents have been 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)
• counsel-[arp]g's parentheses quoting behavior was reversed. Now, if you want literal parentheses, you must escape them: e.g. \(match\) is literal, (match) is a regexp group.