doomemacs/modules/completion/ivy/README.org

#+TITLE: :completion ivy

This module adds Ivy, a completion backend.

#+begin_quote
I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's lighter.
#+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

* 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, 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. Keep in mind that the referenced commands and keybindings are defined [[/modules/private/hlissner][in my private module]].

** Project search & replace
Ex interfaces to Ag (the silver searcher) and Rg (ripgrep) are available: ~:ag[!]~ and ~:rg[!]~, or their current-directory counterparts ~:agcwd[!]~ and ~:rgcwd[!]~.

[[/../screenshots/modules/completion/ivy/ivy-search.gif]]

From this session, you can press =S+Tab= to create a writeable occur-buffer in wgrep mode.

[[/../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 or Unite plugins, and Textmate's Command-T, a marriage of ~projectile~ and ~ivy~ makes this available to you in Emacs. Invoke it with =SPC f /=, =SPC SPC= or ~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/hlissner/+bindings.el][private/hlissner/+bindings.el]]), and their corresponding ex command (defined in [[../../private/hlissner/+commands.el][private/hlissner/+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-buffer~                 | =SPC b b=              | Jump to buffer in current workspace                              |
| ~+ivy/switch-workspace-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)
+ ~counsel-[arp]g~'s parentheses quoting behavior was reversed. Now, if you
  want literal parentheses, you must escape them: e.g. ~\(match\)~ is literal,
 ~(match)~ is a regexp group.