134 lines
6.3 KiB
Org Mode
134 lines
6.3 KiB
Org Mode
#+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)
|
|
|
|
|