emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
doomemacs/modules/completion/ivy/README.org
Henrik Lissner 1911f44e66
completion/ivy: add +icons flag 
This replaces +ivy-buffer-icons.

Renders #1362 unnecessary.
2019-04-25 22:20:31 -04:00

9.1 KiB
Raw Blame History

completion/ivy

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 ag, rg, pt, git-grep & grep (whichever is available).

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 the fuzzy method for ivy searches.
  • +childframe Causes Ivy to display in a floating child frame, above Emacs. This requires GUI Emacs 26.1+
  • +icons Enables file icons for switch-{buffer,project}/find-file counsel commands.

Plugins

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 optionally depends on one of:

Ripgrep is recommended, but the order of its results aren't deterministic and it doesn't support full PCRE (at the time of writing). The_silver_searcher is a good alternative if either of these bother you.

If none of these are installed, file search commands will use git-grep (falling back to grep, otherwise).

Install

MacOS 

brew install ripgrep the_silver_searcher

Arch Linux 

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

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-file project 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 f /, SPC SPC Jump to file in project
SPC f ., SPC . Jump to file from current directory

Project search & replace

This module provides interactive text search and replace using the first search program available on your system (rg, ag, pt, git-grep or grep).

Keybind Description
SPC / b, M-f Search the current buffer
SPC / p Search project
SPC / d Search this directory
SPC p t List all TODO/FIXMEs in project

https://assets.doomemacs.org/completion/ivy/search.png

The +ivy-project-search-engines variable is consulted to determine which underlying program to check for (and in what order). It's default value is '(rg ag pt). If none of these are available, it will resort to git-grep (falling back to grep after that).

To use a specific program, the following engine-specific commands are available (but not bound to any key by default) for searching from the project root or the current directory (recursively), respectively:

  • +ivy/ag / +ivy/ag-from-cwd
  • +ivy/rg / +ivy/rg-from-cwd
  • +ivy/pt / +ivy/pt-from-cwd
  • +ivy/grep / +ivy/grep-from-cwd

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
:ag[!] [QUERY] Search project w/ ag1
:rg[!] [QUERY] Search project w/ rg1
:pt[!] [QUERY] Search project w/ pt1
:grep[!] [QUERY] Search project w/ git-grep/grep1
:agcwd[!] [QUERY] Search this directory w/ the_silver_searcher
:rgcwd[!] [QUERY] Search this directory w/ ripgrep
:ptcwd[!] [QUERY] Search this directory w/ the_platinum_searcher
:grepcwd[!] [QUERY] Search this directory w/ git-grep/grep

The optional BANG functions is equivalent to the universal argument for the previous commands.

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

Keybind Description
S-TAB 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 S-TAB) can be committed with C-c C-c and aborted with C-c C-k.

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 / b
  • M-f
  • :sw[iper] [QUERY]

https://assets.doomemacs.org/completion/ivy/swiper.png

A wgrep buffer can be opened from swiper with S-TAB.

Task lookup

Some projects have TODO's and FIXME's littered across them. The +ivy/tasks command allows you to search and jump to them. It can be invoked with:

  • SPC p t (C-u = restrict search to current file)
  • :todo[!] (BANG = restrict search to current file)

https://assets.doomemacs.org/completion/ivy/todo.png

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 ., SPC . Browse from current directory
SPC f /, SPC p /, 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 / i Search for symbol in current buffer
SPC / I Search for symbol in all similar buffers
SPC / b, M-f Search the current buffer
SPC / p Search project
SPC / d Search this directory
SPC p t List all TODO/FIXMEs in project

Configuration

TODO Enable fuzzy/non-fuzzy search for specific commands

TODO Change the position of the ivy childframe

TODO Troubleshooting