diff --git a/modules/completion/ivy/README.org b/modules/completion/ivy/README.org index 974545c19..f4702a357 100644 --- a/modules/completion/ivy/README.org +++ b/modules/completion/ivy/README.org @@ -1,128 +1,57 @@ -#+TITLE: :completion ivy +#+TITLE: completion/ivy +#+DATE: February 13, 2017 +#+SINCE: v2.0 +#+STARTUP: inlineimages -This module adds Ivy, a completion backend. +* Table of Contents :TOC_3:noexport: +- [[Description][Description]] + - [[Module Flags][Module Flags]] + - [[Plugins][Plugins]] + - [[Hacks][Hacks]] +- [[Prerequisites][Prerequisites]] + - [[Install][Install]] + - [[MacOS][MacOS]] + - [[Arch Linux][Arch Linux]] +- [[Features][Features]] + - [[Jump-to-file project navigation][Jump-to-file project navigation]] + - [[Project search & replace][Project search & replace]] + - [[In-buffer searching][In-buffer searching]] + - [[Task lookup][Task lookup]] + - [[Ivy integration for various completing commands][Ivy integration for various completing commands]] + - [[General][General]] + - [[Jump to files, buffers or projects)][Jump to files, buffers or projects)]] + - [[Search][Search]] +- [[Configuration][Configuration]] + - [[Enable fuzzy/non-fuzzy search for specific commands][Enable fuzzy/non-fuzzy search for specific commands]] + - [[Change the position of the ivy childframe][Change the position of the ivy childframe]] +- [[Troubleshooting][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). #+begin_quote I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's -lighter. +lighter, simpler and faster in many cases. #+end_quote -+ 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 +** 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+* -* Table of Contents :TOC: -- [[#install][Install]] - - [[#macos][MacOS]] - - [[#arch-linux][Arch Linux]] -- [[#usage][Usage]] - - [[#project-search--replace][Project search & replace]] - - [[#jump-to-file-project-navigation][Jump-to-file project navigation]] - - [[#in-buffer-searching][In-buffer searching]] - - [[#task-lookup][Task lookup]] -- [[#appendix][Appendix]] - - [[#commands][Commands]] - - [[#hacks][Hacks]] - -* Install -This module optionally depends on [[https://github.com/BurntSushi/ripgrep][ripgrep]] and [[https://github.com/ggreer/the_silver_searcher][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 -#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes") -brew install ripgrep the_silver_searcher -#+END_SRC - -** Arch Linux -#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes") -sudo pacman --needed --noconfirm -S ripgrep the_silver_searcher -#+END_SRC - -* 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). - -[[/../screenshots/modules/completion/ivy/ivy-search.gif]] - -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. - -[[/../screenshots/modules/completion/ivy/ivy-search-replace.gif]] - -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~. - -[[/../screenshots/modules/completion/ivy/ivy-projectile.gif]] - -** 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]~). - -[[/../screenshots/modules/completion/ivy/ivy-swiper.gif]] - -** 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). - -[[/../screenshots/modules/completion/ivy/ivy-todo.gif]] - -* Appendix -** Commands -Here is a list of my commonly used commands, their default keybinds (defined in -[[../../private/default/+bindings.el][private/default/+bindings.el]]), and their corresponding ex command (defined in -[[../../private/default/+evil-commands.el][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 | -|-------------+--------------------------------------------------------------------------------| -| == | 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 | +** Plugins ++ [[https://github.com/abo-abo/swiper][ivy]] ++ [[https://github.com/abo-abo/swiper][counsel]] ++ [[https://github.com/ericdanan/counsel-projectile][counsel-projectile]] ++ [[https://github.com/abo-abo/swiper][swiper]] ++ [[https://github.com/abo-abo/swiper][ivy-hydra]] ++ [[https://github.com/yevgnen/ivy-rich][ivy-rich]] ++ [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]] ++ [[https://github.com/DarwinAwardWinner/amx][amx]] ++ [[https://github.com/lewang/flx][flx]]* (=+fuzzy=) ++ [[https://github.com/tumashu/ivy-posframe][ivy-posframe]]* (=+childframe=) ** Hacks + Functions with ivy/counsel equivalents have been globally remapped (like @@ -131,4 +60,161 @@ keybindings are available to you: + ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex command) +* Prerequisites +This module optionally depends on one of: ++ [[https://github.com/BurntSushi/ripgrep][ripgrep]] (rg) ++ [[https://github.com/ggreer/the_silver_searcher][the_silver_searcher]] (ag) ++ [[https://github.com/monochromegane/the_platinum_searcher][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 +#+BEGIN_SRC sh +brew install ripgrep the_silver_searcher +#+END_SRC + +*** Arch Linux +#+BEGIN_SRC sh :dir /sudo:: +sudo pacman --needed --noconfirm -S ripgrep the_silver_searcher +#+END_SRC + +* 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/ ag[fn:1] | +| ~:rg[!] [QUERY]~ | Search project w/ rg[fn:1] | +| ~:pt[!] [QUERY]~ | Search project w/ pt[fn:1] | +| ~:grep[!] [QUERY]~ | Search project w/ git-grep/grep[fn:1] | +| ~: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