doomemacs/modules/completion/ivy/README.org

:completion ivy

• Table of Contents
• Install
  • MacOS
  • Arch Linux
• Usage
  • Project search & replace
  • Jump-to-file project navigation
  • In-buffer searching
  • Task lookup
• Appendix
  • Commands
  • Hacks

This module adds Ivy, a completion backend.

I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's lighter.

• Project-wide search & replace powered by rg or 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

Table of Contents   TOC

• Install

  • MacOS
  • Arch Linux

• Usage

  • Project search & replace
  • Jump-to-file project navigation
  • In-buffer searching
  • Task lookup

• Appendix

  • Commands
  • Hacks

Install

This module optionally depends on ripgrep and the_silver_searcher.

rg is faster, but its results aren't deterministic, neither does it support multiline search or full PCRE (at the time of writing), 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

Here is some insight into how I use this module.

Project search & replace

There are four Ex interfaces for the silver searcher and ripgrep. They are:

• :ag[!]
• :agcwd[!]
• :rg[!]
• :rgcwd[!]

The optional BANG tells ag/rg to include ignored files in the search. And the \*cwd variant of each command will only search in the current directory (non-recursively).

Now, how do we do text replacements? With the ivy popup open you can press S+Tab to create an wgrep buffer out of the results.

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/Unite plugins, and Textmate's Command-T, a marriage of projectile and ivy makes this available in Emacs.

Invoke it with SPC f /, SPC SPC or M-x counsel-projectile-find-file.

In-buffer searching

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

Task lookup

I sprinkle my projects with TODO's & FIXME's. You can navigate to and peruse them via M-x +ivy/tasks or :todo[!] (ex command).

Appendix

Commands

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

command	key / ex command	description
counsel-M-x	M-x	Smarter, smex-powered M-x
counsel-bookmark	SPC RET	Find bookmark
counsel-find-file	SPC f . or SPC .	Browse from current directory
counsel-projectile-find-file	SPC f / or SPC SPC	Find file in project
counsel-projectile-switch-project	SPC p p	Open another project
counsel-recentf	SPC f r	Find recently opened file
+ivy/switch-workspace-buffer	SPC b b	Jump to buffer in current workspace
ivy-switch-buffer	SPC b B	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

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