#+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 (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                                                                    |
|-------------+--------------------------------------------------------------------------------|
| =<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)