History

Henrik Lissner 0a7221798b Start file searchs from basic sh/dash shell Uses the most basic, uncustomized shell to a) prevent interference caused by slow shell configs and b) speed up project text searches. This comes at the cost of isolating these programs from envvars that the user may have set in their shell configs in order to change ag/rg/pt/git-grep/grep's behavior. If this bothers you, change +ivy-file-search-shell to your shell (or to the value of `shell-file-name`). Possibly relevant to an issue mentioned in #1260		2019-06-17 15:10:55 +02:00
..
autoload
config.el
doctor.el
packages.el
README.org

README.org

completion/ivy

Description
Prerequisites
- Install
  - MacOS
  - Arch Linux
Features
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 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 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. This requires GUI Emacs 26.1+
+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 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`	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/ ag¹
`:rg[!] [QUERY]`	Search project w/ rg¹
`:pt[!] [QUERY]`	Search project w/ pt¹
`:grep[!] [QUERY]`	Search project w/ git-grep/grep¹
`: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
`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 / b
:sw[iper] [QUERY]

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

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)

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`	Search the current buffer
`SPC / p`	Search project
`SPC / d`	Search this directory
`SPC p t`	List all TODO/FIXMEs in project