149b2617b0
This is second of three big naming convention changes. In this commit,
we change the naming conventions for hook functions and variable
functions:
1. Replace the bar | to indicate a hook function with a -h suffix, e.g.
doom|init-ui -> doom-init-ui-h
doom|run-local-var-hooks -> doom-run-local-var-hooks-h
2. And add a -fn suffix for functions meant to be set on variables,
e.g.
(setq magit-display-buffer-function #'+magit-display-buffer-fn)
See ccf327f8 for the reasoning behind these changes.
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
+fuzzyEnables fuzzy completion for Ivy searches.+prescientEnables prescient filtering and sorting for Ivy searches.+childframeCauses Ivy to display in a floating child frame, above Emacs. This requires GUI Emacs 26.1++iconsEnables 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 tofind-filewill invokecounsel-find-fileinstead. 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 (rg)
- the_silver_searcher (ag)
- the_platinum_searcher (pt)
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_searcherArch Linux
sudo pacman --needed --noconfirm -S ripgrep the_silver_searcherFeatures
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/ 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 |
|---|---|
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 |